codex-workflows 0.2.3 → 0.2.5

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

@@ -110,6 +110,11 @@ Each AC is written in EARS (Easy Approach to Requirements Syntax) format.
 - **Integration Target**: [What to connect with]
 - **Invocation Method**: [How it will be invoked]
 
+### Dependency Verification
+| Dependency | Status | Evidence |
+|------------|--------|----------|
+| [Service / hook / type / table / endpoint] | [verified-existing / requires-new-creation / external-dependency] | [path:line, search evidence, or authoritative external source] |
+
 ### Code Inspection Evidence
 
 | File/Function | Relevance |
@@ -259,40 +264,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/document-reviewer.toml

@@ -92,6 +92,7 @@ Verify required elements exist per documentation-criteria skill template. Gate 0
 For DesignDoc, additionally verify:
 - [ ] Code inspection evidence recorded (files and functions listed)
 - [ ] Applicable standards listed with explicit/implicit classification
+- [ ] Dependencies described as existing have verification results or authoritative external source
 - [ ] Field propagation map present (when fields cross boundaries)
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
@@ -106,6 +107,7 @@ For DesignDoc, additionally verify:
 - Technical information verification: When sources exist, verify with web search for latest information and validate claim validity
 - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
+- Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using file pattern search and content search. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but the definition signature or named contract materially diverges from the Design Doc description → `important` issue (category: `consistency`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
 - **Undetermined items review** [MANDATORY]: Every TBD, unknown, or open item MUST include: (1) **owner** — who resolves it, (2) **due** — when it gets resolved (which phase or milestone), (3) **next-phase handling** — how the next phase treats this gap. Missing any of these three → `important` issue
 
@@ -259,6 +261,7 @@ Include in output when `prior_context_count > 0`:
 - [ ] Gate 0 structural existence checks pass before quality review
 - [ ] Design decision rationales verified against identified standards/patterns
 - [ ] Code inspection evidence covers files relevant to design scope
+- [ ] Dependencies described as existing verified against codebase or authoritative external source
 - [ ] Field propagation map present when fields cross component boundaries
 
 ## Review Criteria (for Comprehensive Mode)

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

@@ -84,9 +84,17 @@ Must be performed before Design Doc creation:
      - Similar component is technical debt → Create ADR improvement proposal before implementation
      - No similar component → Proceed with new implementation
 
-4. **Include in Design Doc**
+4. **Dependency Existence Verification**
+   - For each component the design assumes already exists, search for its definition in the codebase using file pattern search and content search
+   - Typical targets include: components, custom hooks, Context definitions, store/state definitions, API endpoints, type definitions, utility functions
+   - If found in codebase: record file path and definition location
+   - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
+   - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect this in implementation order dependencies
+
+5. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar component search results (found components or "none")
+   - Include dependency existence verification results (verified existing / requires new creation / external dependency)
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
 ### Integration Points【Important】
@@ -338,9 +346,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

@@ -101,12 +101,20 @@ Must be performed before Design Doc creation:
      - Similar functionality is technical debt → Create ADR improvement proposal before implementation
      - No similar functionality → Proceed with new implementation
 
-4. **Include in Design Doc**
+4. **Dependency Existence Verification**
+   - For each dependency the design assumes already exists, search for its definition in the codebase using file pattern search and content search
+   - Typical targets include: interfaces, classes, repositories, service methods, API endpoints, DB tables/columns, configuration keys, enum values, type definitions
+   - If found in codebase: record file path and definition location
+   - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
+   - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect this in implementation order dependencies
+
+5. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar functionality search results (found implementations or "none")
+   - Include dependency existence verification results (verified existing / requires new creation / external dependency)
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
-5. **Code Inspection Evidence**
+6. **Code Inspection Evidence**
    - Record all inspected files and key functions in "Code Inspection Evidence" section of Design Doc
    - Each entry must state relevance (similar functionality / integration point / pattern reference)
 
@@ -314,9 +322,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.5",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",