codex-workflows 0.2.3 → 0.2.4

package/.agents/skills/documentation-criteria/SKILL.md

@@ -64,16 +64,16 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 ### UI Specification
 **Purpose**: Define UI structure, screen transitions, component decomposition, and interaction design
 **Includes**: Screen list and transitions, component state x display matrix, interaction definitions, AC traceability, existing component reuse map, accessibility requirements
-**Excludes**: Technical implementation details, API contracts, test implementation, implementation schedule
+**Excludes**: Technical implementation details, API contracts, test implementation (generated by acceptance-test-generator), implementation schedule
 
 ### Design Document
 **Purpose**: Define technical implementation methods in detail
 **Includes**: Existing codebase analysis, technical approach, dependencies and constraints, interface/contract definitions, data flow, acceptance criteria, change impact map, code inspection evidence
-**Excludes**: Why that technology was chosen (reference ADR), when/who to implement (reference Work Plan)
+**Excludes**: Why that technology was chosen (reference ADR), when/who to implement (reference Work Plan), detailed test strategy and test case selection (generated by acceptance-test-generator from acceptance criteria)
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**Includes**: Task breakdown, schedule estimates, E2E verification procedures, Phase 4 Quality Assurance Phase (required), progress records
+**Includes**: Task breakdown, schedule estimates, test skeleton file paths, Phase 4 Quality Assurance Phase (required), progress records
 **Excludes**: Technical rationale, design details
 
 **Phase Division Criteria**:

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

@@ -259,40 +259,15 @@ System Invariants:
    - Prerequisites: [Required pre-implementations]
 
 ### Integration Points
-Each integration point requires E2E verification:
 
 **Integration Point 1: [Name]**
 - Components: [Component A] to [Component B]
-- Verification: [How to verify integration works]
+- Contract: [Interface/API contract between components]
 
 ### Migration Strategy
 
 [Technical migration approach, ensuring backward compatibility]
 
-## Test Strategy
-
-### Basic Test Design Policy
-
-Automatically derive test cases from acceptance criteria:
-- Create at least one test case for each acceptance criterion
-- Implement measurable standards from acceptance criteria as assertions
-
-### Unit Tests
-
-[Unit testing policy and coverage goals]
-
-### Integration Tests
-
-[Integration testing policy and important test cases]
-
-### E2E Tests
-
-[E2E testing policy]
-
-### Performance Tests
-
-[Performance testing methods and standards]
-
 ## Security Considerations
 
 Evaluate the following for this feature's trust boundaries and data flow:

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

@@ -48,11 +48,6 @@ Related Issue/PR: #XXX (if any)
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
 
-#### Operational Verification Procedures
-1. [Operation verification steps]
-2. [Expected result verification]
-3. [Performance verification (when applicable)]
-
 ### Phase 2: [Phase Name] (Estimated commits: X)
 **Purpose**: [What this phase aims to achieve]
 
@@ -66,11 +61,6 @@ Related Issue/PR: #XXX (if any)
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
 
-#### Operational Verification Procedures
-1. [Operation verification steps]
-2. [Expected result verification]
-3. [Performance verification (when applicable)]
-
 ### Phase 3: [Phase Name] (Estimated commits: X)
 **Purpose**: [What this phase aims to achieve]
 
@@ -84,9 +74,6 @@ Related Issue/PR: #XXX (if any)
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
 
-#### Operational Verification Procedures
-[Copy relevant integration point operational verification from Design Doc]
-
 ### Final Phase: Quality Assurance (Required) (Estimated commits: 1)
 **Purpose**: Overall quality assurance and Design Doc consistency verification
 
@@ -94,13 +81,10 @@ Related Issue/PR: #XXX (if any)
 - [ ] Verify all Design Doc acceptance criteria achieved
 - [ ] Security review: Verify security considerations from Design Doc are implemented
 - [ ] Quality checks (types, lint, format)
-- [ ] Execute all tests
+- [ ] Execute all tests (including integration/E2E from test skeletons, when provided)
 - [ ] Coverage 70%+
 - [ ] Document updates
 
-#### Operational Verification Procedures
-[Copy operational verification procedures from Design Doc]
-
 ### Quality Assurance
 - [ ] Implement staged quality checks (details: refer to ai-development-guide skill)
 - [ ] All tests pass
@@ -110,7 +94,8 @@ Related Issue/PR: #XXX (if any)
 
 ## Completion Criteria
 - [ ] All phases completed
-- [ ] Each phase's operational verification procedures executed
+- [ ] All integration/E2E tests passing (when test skeletons provided)
+- [ ] Acceptance criteria manually verified (when test skeletons are not provided)
 - [ ] Design Doc acceptance criteria satisfied
 - [ ] Staged quality checks completed (zero errors)
 - [ ] All tests pass

package/.agents/skills/recipe-add-integration-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: recipe-add-integration-tests
-description: "Add integration/E2E tests to existing codebase using Design Doc acceptance criteria."
+description: "Add integration/E2E tests to existing codebase using Design Docs."
 ---
 
 ## Required Skills [LOAD BEFORE EXECUTION]
@@ -26,11 +26,11 @@ description: "Add integration/E2E tests to existing codebase using Design Doc ac
 - Test review -> Spawn integration-test-reviewer agent
 - Quality checks -> Spawn quality-fixer agent
 
-Design Doc path: $ARGUMENTS
+Document paths: $ARGUMENTS
 
 ## Prerequisites
 
-- Design Doc must exist (created manually or via reverse-engineer)
+- At least one Design Doc must exist (created manually or via reverse-engineer)
 - Existing implementation to test
 
 ## Execution Flow
@@ -39,27 +39,59 @@ Design Doc path: $ARGUMENTS
 
 Reference documentation-criteria skill for task file template in Step 3.
 
-### Step 1: Validate Design Doc
+### Step 1: Discover and Validate Documents
 
-Verify Design Doc exists at $ARGUMENTS or find the most recent in docs/design/.
+```bash
+# Verify at least one document path was provided
+test -n "$ARGUMENTS" || { echo "ERROR: No document paths provided"; exit 1; }
+
+# Verify provided paths exist
+ls $ARGUMENTS
+```
+
+Use only the user-provided paths in `$ARGUMENTS`. Do not auto-discover additional Design Docs or UI Specs.
+
+Classify provided documents by path and filename, using first-match-wins:
+- Path matches `docs/ui-spec/*.md` -> **UI Spec**
+- Path matches `docs/design/*-backend-*.md` or `docs/design/*backend*.md` -> **Design Doc (backend)**
+- Path matches `docs/design/*-frontend-*.md` or `docs/design/*frontend*.md` -> **Design Doc (frontend)**
+- Path matches `docs/design/*.md` and none of the above -> **single-layer Design Doc**
+
+If a filename appears to match both backend and frontend, halt and ask the user which layer it belongs to.
 
 ### Step 2: Skeleton Generation
 
-Spawn acceptance-test-generator agent: "Generate test skeletons from Design Doc at [path from Step 1]."
+Spawn acceptance-test-generator agent with only the documents that exist from Step 1:
+```text
+Generate test skeletons from the following documents:
+- Design Doc (backend): [path]    <- include only if exists
+- Design Doc (frontend): [path]   <- include only if exists
+- UI Spec: [path]                 <- include only if exists
+```
 
-**Expected output**: `generatedFiles` containing integration and e2e paths
+**Expected output**: `generatedFiles` as a structured object grouped by layer, for example:
+```json
+{
+  "backend": ["path/to/backend.int.test.ts"],
+  "frontend": ["path/to/frontend.int.test.ts"],
+  "e2e": ["path/to/flow.e2e.test.ts"]
+}
+```
 
-### Step 3: Create Task File [GATE]
+### Step 3: Create Task Files [GATE]
 
 **[STOP — BLOCKING]** Present task file content to user for confirmation before proceeding to implementation.
 **CANNOT proceed until user explicitly confirms.**
 
-Create task file at: `docs/plans/tasks/integration-tests-YYYYMMDD.md`
+Create one task file per layer, using the monorepo-flow.md naming convention for deterministic agent routing:
+- Backend skeletons exist -> `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md`
+- Frontend skeletons exist -> `docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md`
+- Single-layer (no backend/frontend distinction) -> `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md`
 
-**Template**:
+**Template** (per task file):
 ```markdown
 ---
-name: Implement integration tests for [feature name]
+name: Implement [layer] integration tests for [feature name]
 type: test-implementation
 ---
 
@@ -69,8 +101,8 @@ Implement test cases defined in skeleton files.
 
 ## Target Files
 
-- Skeleton: [path from Step 2 generatedFiles]
-- Design Doc: [path from Step 1]
+- Skeleton: [layer-specific paths from Step 2 generatedFiles]
+- Design Doc: [layer-specific Design Doc from Step 1]
 
 ## Tasks
 
@@ -85,17 +117,22 @@ Implement test cases defined in skeleton files.
 - No quality issues
 ```
 
-**Output**: "Task file created at [path]. Ready for Step 4."
+**Output**: "Task file(s) created at [path(s)]. Ready for Step 4."
 
 ### Step 4: Test Implementation
 
-Spawn task-executor agent: "Implement integration tests. Task file: docs/plans/tasks/integration-tests-YYYYMMDD.md. Implement tests following the task file."
+For each task file from Step 3, invoke task-executor routed by filename pattern:
+- `*-backend-task-*` -> Spawn `task-executor`
+- `*-frontend-task-*` -> Spawn `task-executor-frontend`
+- Prompt: "Task file: [task file path from Step 3]. Implement tests following the task file."
+
+Execute one task file at a time through Steps 4 -> 5 -> 6 -> 7 before starting the next.
 
 **Expected output**: `status`, `testsAdded`
 
 ### Step 5: Test Review
 
-Spawn integration-test-reviewer agent: "Review test quality. Test files: [paths from Step 4 testsAdded]. Skeleton files: [paths from Step 2 generatedFiles]."
+Spawn integration-test-reviewer agent: "Review test quality. Test files: [paths from Step 4 testsAdded]. Skeleton files: [layer-specific paths from Step 2 generatedFiles matching current task's layer]."
 
 **Expected output**: `status` (approved/needs_revision), `requiredFixes`
 
@@ -103,11 +140,14 @@ Spawn integration-test-reviewer agent: "Review test quality. Test files: [paths
 
 Check Step 5 result:
 - `status: approved` -> Mark complete, proceed to Step 7
-- `status: needs_revision` -> Spawn task-executor agent: "Fix the following issues in test files: [requiredFixes from Step 5]." Then return to Step 5.
+- `status: needs_revision` -> Spawn the layer-appropriate executor with: "Fix the following issues in test files: [requiredFixes from Step 5]." Then return to Step 5. Maximum 2 revision cycles per task file; if still `needs_revision`, escalate to the user.
 
 ### Step 7: Quality Check
 
-Spawn quality-fixer agent: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage."
+Spawn quality-fixer routed by task filename pattern:
+- `*-backend-task-*` -> Spawn `quality-fixer`
+- `*-frontend-task-*` -> Spawn `quality-fixer-frontend`
+- Prompt: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage."
 
 **Expected output**: `status` (`approved`/`blocked`)
 

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

@@ -106,7 +106,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - **Phase Completion Task Auto-generation (Required)**:
      - Based on "Phase X" notation in work plan, generate after each phase's final task
      - Filename: `{plan-name}-phase{number}-completion.md`
-     - Content: Copy E2E verification procedures from Design Doc, all task completion checklist
+     - Content: All task completion checklist, list test skeleton file paths for verification
      - Criteria: Always generate if the plan contains the string "Phase"
 
 5. **Task Structuring**

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

@@ -338,9 +338,9 @@ function useUserData(userId: string) {
 - [ ] **Agreement checklist completed** (most important)
 - [ ] **Prerequisite common ADRs referenced** (required)
 - [ ] **Change impact map created** (required)
-- [ ] **Component verification procedures for each phase** (required)
 - [ ] Response to requirements and design validity
-- [ ] Test strategy (React Testing Library) and error handling (Error Boundary)
+- [ ] Error handling strategy
+- [ ] Acceptance criteria written in testable format: each criterion includes a measurable condition and expected outcome (verifiable by acceptance-test-generator)
 - [ ] Props change matrix completeness
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest React best practices researched and references cited

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

@@ -314,9 +314,9 @@ Implementation sample creation checklist:
 - [ ] **Agreement checklist completed** (most important)
 - [ ] **Prerequisite common ADRs referenced** (required)
 - [ ] **Change impact map created** (required)
-- [ ] **E2E verification procedures for each phase** (required)
 - [ ] Response to requirements and design validity
-- [ ] Test strategy and error handling
+- [ ] Error handling strategy
+- [ ] Acceptance criteria written in testable format: each criterion includes a measurable condition and expected outcome (verifiable by acceptance-test-generator)
 - [ ] Interface change matrix completeness
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest best practices researched and references cited

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

@@ -40,7 +40,7 @@ Skill Status:
 2. Clarify task dependencies
 3. Phase division and prioritization
 4. Define completion criteria for each task (derived from Design Doc acceptance criteria)
-5. Define operational verification procedures for each phase
+5. Place test implementation and execution appropriately for each phase
 6. Concretize risks and countermeasures
 7. Document in progress-trackable format
 
@@ -60,7 +60,7 @@ Skill Status:
 Read the Design Doc(s), UI Spec, PRD, and ADR (if provided). Extract:
 - Acceptance criteria and implementation approach
 - Technical dependencies and implementation order
-- Integration points requiring E2E verification
+- Integration points and their contracts
 
 ### 2. Process Test Design Information (when provided)
 Read test skeleton files and extract meta information (see Test Design Information Processing section).
@@ -71,7 +71,8 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati
 ### 4. Compose Phases
 Structure phases based on technical dependencies from Design Doc:
 - Place tasks with lowest dependencies in earlier phases
-- Include operational verification at integration points
+- 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 not provided, include test implementation tasks based on Design Doc acceptance criteria
 - Include quality assurance in final phase
 
 ### 5. Define Tasks with Completion Criteria
@@ -206,8 +207,8 @@ Verification: L1 — [specific verification method]
 Compose phases based on technical dependencies and implementation approach from Design Doc.
 Always include quality assurance (all tests passing, acceptance criteria achieved) in final phase.
 
-### Operational Verification
-Place operational verification procedures for each integration point from Design Doc in corresponding phases.
+### Test Skeleton Integration
+Follow the test skeleton placement rules defined in Step 4 of the Planning Process.
 
 ## Diagram Creation (using mermaid notation)
 
@@ -219,7 +220,7 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 - [ ] Phase composition based on technical dependencies
 - [ ] All requirements converted to tasks
 - [ ] Quality assurance exists in final phase
-- [ ] E2E verification procedures placed at integration points
+- [ ] Test skeleton file paths listed in corresponding phases (when 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.3",
+  "version": "0.2.4",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",