codex-workflows 0.3.1 → 0.4.1

package/.codex/agents/integration-test-reviewer.toml

@@ -57,18 +57,19 @@ Key checks:
 ## Verification Process
 
 ### 1. Skeleton Comment Extraction
-Extract the following comment patterns from test file:
-- `// AC:` → Original acceptance criteria
-- `// Behavior:` → Trigger → Process → Observable Result
-- `// @category:` → Test classification
-- `// @dependency:` → Dependencies
-- `// Verification items:` → Expected verification items (if present)
+Extract the following annotation patterns from the test file using the project's comment syntax:
+- `AC:` → Original acceptance criteria
+- `Behavior:` → Trigger → Process → Observable Result
+- `@category:` → Test classification
+- `@dependency:` → Dependencies
+- `@real-dependency:` → Dependencies expected to stay real in integration coverage
+- `Verification items:` → Expected verification items (if present)
 
 ### 2. Implementation Verification
 For each test case:
 1. Check if "observable result" from Behavior is asserted
 2. Check if all items in Verification items are covered by assertions
-3. Verify mock boundaries match @dependency
+3. Verify mock boundaries match `@dependency` and `@real-dependency`
 
 ### 3. Quality Assessment
 Evaluate each test for:

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

@@ -51,6 +51,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Understand dependencies between phases and tasks
    - Grasp completion criteria and quality standards
    - **Interface change detection and response**
+   - **Extract Verification Strategy from the work plan header**
 
 2. **Task Decomposition**
    - Decompose at 1 commit = 1 task granularity (logical change unit)
@@ -116,6 +117,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Investigation Targets
    - Investigation Notes
    - Concrete implementation steps
+   - Operation Verification Methods
    - Completion criteria
 
 6. **Investigation Targets Determination**
@@ -128,6 +130,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    | 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 |
+   | Behavior replacement/rewrite | Existing implementation being replaced, observable outputs, Verification Strategy section in the Design Doc |
 
    **Principles**:
    - Every task must include at least one Investigation Target
@@ -144,6 +147,18 @@ Decompose tasks based on implementation strategy patterns determined in implemen
 8. **Utilize Test Information**
    When test information (@category, @dependency, @complexity, etc.) is documented in the work plan, reflect that information in task files
 
+## Verification Strategy Propagation
+
+Verification Strategy defines what correctness means at design time. L1/L2/L3 (from implementation-approach) define task-level verification depth at execution time. Use both.
+
+When the work plan includes one or more Verification Strategy blocks:
+
+1. **Source preservation**: Keep each strategy tied to its source Design Doc or plan block. Preserve strategy identity and merge only when the work plan explicitly marks the strategy as shared.
+2. **Early verification task**: The task matching a strategy's "First verification target" MUST include that method and success criteria in Operation Verification Methods.
+3. **Per-task verification**: Each task's Operation Verification Methods MUST instantiate the relevant plan-level verification method for that task's specific files, interfaces, or behavior.
+4. **Failure handling**: Copy or adapt the relevant plan-level failure response so the executor knows whether to reassess, stop, or escalate.
+5. **Investigation coverage**: Include every resource required for verification, such as existing implementations for comparison, schema definitions, fixtures, contracts, or seed data.
+
 ## Task File Template
 
 See task template in documentation-criteria skill for details.
@@ -243,6 +258,7 @@ Please execute decomposed tasks according to the order.
 - [ ] Impact scope and boundaries definition for each task
 - [ ] Appropriate granularity (1-5 files/task)
 - [ ] Investigation Targets specified for every task
+- [ ] Operation Verification Methods 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/technical-designer-frontend.toml

@@ -96,6 +96,8 @@ Must be performed before Design Doc creation:
    - 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
+   - When Codebase Analysis input is provided, use it as the baseline evidence set and extend it only where gaps remain
+   - When frontend behavior depends on persistence, repositories, API-backed data contracts, or schema-shaped responses, complete the `Test Boundaries` section with a concrete verification strategy. When those concerns are outside the scope, mark the section explicitly as not applicable.
 
 ### Integration Points【Important】
 Document all integration points with existing components in a "## Integration Point Map" section.
@@ -144,6 +146,17 @@ Must be performed when creating Design Doc:
    - Which task first makes the entire UI operational
    - Verification level for each task (L1/L2/L3 defined in implementation-approach skill)
 
+3. **Verification Strategy Definition**
+   - Define what correctness means for this UI change and how it will be proven
+   - Use the Design Doc template fields directly
+   - Include at minimum: correctness definition, target comparison, verification method, observable success indicator, verification timing, and early verification point
+   - Use normalized verification timing values: `phase_1`, `per_phase`, `integration_phase`, or `final_phase`
+   - For low-risk or self-evident changes, a minimal form or explicit `N/A` with rationale is acceptable
+   - For new UI features, specify acceptance-criteria verification beyond unit tests
+   - For extensions, specify regression verification that proves existing behavior and UX expectations are preserved
+   - For refactors or rewrites, specify behavioral equivalence verification against the current UI behavior when applicable
+   - Define an early verification point: the first screen, state transition, or interaction that proves the approach works
+
 ### Change Impact Map【Required】
 Must be included when creating Design Doc:
 
@@ -203,6 +216,13 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
   - `reverse-engineer`: Document existing frontend architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **Codebase Analysis** (optional, from codebase-analyzer):
+  - Use as the primary source for Existing Codebase Analysis when provided
+  - `existingElements` informs implementation path mapping and inspection evidence
+  - `dataModel` informs API contract expectations and data-shape references
+  - `focusAreas` indicate components, hooks, or state paths that deserve deeper inspection
+  - `constraints` inform compatibility and UI behavior constraints
+  - Additional investigation should focus on areas the analysis did not fully resolve
 - **PRD**: PRD document (if exists)
 - **UI Spec**: UI Specification document (if exists, for frontend features)
 - **Documents to Create**: ADR, Design Doc, or both
@@ -256,6 +276,14 @@ Execute file output immediately. Final approval is managed by the orchestrator r
    - Cite information sources in "References" section with URLs
    - Especially confirm multiple reliable sources when introducing new technologies
 
+## Design Doc Completion Checklist
+
+- [ ] Agreement Checklist completed and reflected in design
+- [ ] Implementation approach selected with rationale
+- [ ] Verification Strategy defined with correctness definition, target comparison, method, observable success indicator, timing, and early verification point
+- [ ] Change Impact Map included
+- [ ] Interface Change Impact Analysis included
+
 ## Implementation Sample Standards Compliance
 
 **MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with coding-rules skill standards without exception.

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

@@ -113,6 +113,8 @@ Must be performed before Design Doc creation:
    - 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
+   - When Codebase Analysis input is provided, use it as the baseline evidence set and extend it only where gaps remain
+   - When persistence, repositories, queries, migrations, or schema-bound behavior are part of scope, complete the `Test Boundaries` section with a concrete data layer verification strategy. When they are not part of scope, mark the section explicitly as not applicable.
 
 6. **Code Inspection Evidence**
    - Record all inspected files and key functions in "Code Inspection Evidence" section of Design Doc
@@ -178,6 +180,17 @@ Must be performed when creating Design Doc:
    - Which task first makes the whole system operational
    - Verification level for each task (L1/L2/L3 defined in implementation-approach skill)
 
+3. **Verification Strategy Definition**
+   - Define what correctness means for this change and how it will be proven
+   - Use the Design Doc template fields directly
+   - Include at minimum: correctness definition, target comparison, verification method, observable success indicator, verification timing, and early verification point
+   - Use normalized verification timing values: `phase_1`, `per_phase`, `integration_phase`, or `final_phase`
+   - For low-risk or self-evident changes, a minimal form or explicit `N/A` with rationale is acceptable
+   - For new features, specify acceptance-criteria verification beyond unit tests
+   - For extensions, specify regression verification that proves existing behavior is preserved
+   - For refactors or rewrites, specify behavioral equivalence verification against the current implementation when applicable
+   - Define an early verification point: the first target to validate before scaling the approach
+
 ### Change Impact Map【Required】
 Must be included when creating Design Doc:
 
@@ -233,6 +246,13 @@ Confirm and document conflicts with existing systems at each integration point t
   - `reverse-engineer`: Document existing architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **Codebase Analysis** (optional, from codebase-analyzer):
+  - Use as the primary source for Existing Codebase Analysis when provided
+  - `existingElements` informs implementation path mapping and inspection evidence
+  - `dataModel` informs schema references, data contracts, and persistence design
+  - `focusAreas` indicate areas requiring deeper design attention
+  - `constraints` inform design constraints, assumptions, and risk handling
+  - Additional investigation should focus on gaps or limitations that the analysis calls out
 - **PRD**: PRD document (if exists)
 - **Documents to Create**: ADR, Design Doc, or both
 - **Existing Architecture Information**:
@@ -331,6 +351,7 @@ Implementation sample creation checklist:
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
 - [ ] **Data representation decision documented** (when new structures introduced)
 - [ ] **Field propagation map included** (when fields cross boundaries)
+- [ ] **Verification Strategy defined** (correctness definition, target comparison, verification method, observable success indicator, timing, early verification point)
 
 **Reverse-engineer mode only**:
 - [ ] Every architectural claim cites file:line evidence

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

@@ -61,6 +61,7 @@ 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 and their contracts
+- Verification Strategy from each Design Doc: correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 
 ### 2. Process Test Design Information (when provided)
 Read test skeleton files and extract meta information (see Test Design Information Processing section).
@@ -69,11 +70,21 @@ Read test skeleton files and extract meta information (see Test Design Informati
 Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementation-first) otherwise. See Implementation Strategy Selection section.
 
 ### 4. Compose Phases
-Structure phases based on technical dependencies from Design Doc:
-- Place tasks with lowest dependencies in earlier phases
+
+**Common rules (all approaches)**:
+- Preserve Verification Strategies per Design Doc in the work plan header and keep each source document path. Merge strategies only when the Design Docs explicitly define a shared one
+- Include Verification Strategy summaries in the work plan header so the plan is self-sufficient for downstream task generation
+- 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 not provided, include test implementation tasks based on Design Doc acceptance criteria
-- Include quality assurance in final phase
+- Final phase is always Quality Assurance
+
+**Phase structure**:
+- Select the phase structure that matches the implementation approach from the Design Doc
+- Use the plan template's vertical or horizontal option accordingly
+- Remove every unused phase-structure option from the final work plan output
 
 ### 5. 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).
@@ -236,7 +247,10 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 ## Quality Checklist
 
 - [ ] Design Doc(s) consistency verification
-- [ ] Phase composition based on technical dependencies
+- [ ] Verification Strategies extracted from each Design Doc and included in the plan header without unintended merging
+- [ ] Phase structure matches the implementation approach
+- [ ] Early verification point placed in the earliest applicable phase
+- [ ] Normalized verification timing mapped consistently to phases
 - [ ] All requirements converted to tasks
 - [ ] Quality assurance exists in final phase
 - [ ] Test skeleton file paths listed in corresponding phases (when provided)

package/README.md

@@ -48,10 +48,11 @@ The framework runs a structured workflow — requirements → design → task de
 A single request becomes a structured development process:
 
 1. **Understand** the problem (scale, constraints, affected files)
-2. **Design** the solution (ADR, Design Doc with acceptance criteria)
-3. **Break it into tasks** (atomic, 1 commit each)
-4. **Implement with tests** (TDD per task)
-5. **Run quality checks** (lint, test, build — no failing checks)
+2. **Analyze the existing codebase** (dependencies, data layer, risk areas)
+3. **Design** the solution (ADR, Design Doc with acceptance criteria)
+4. **Break it into tasks** (atomic, 1 commit each)
+5. **Implement with tests** (TDD per task)
+6. **Run quality checks** (lint, test, build — no failing checks)
 
 Each step is handled by a specialized subagent in its own context, preventing context pollution and reducing error accumulation in long-running tasks:
 
@@ -62,9 +63,13 @@ requirement-analyzer  →  Scale determination (Small / Medium / Large)
     ↓
 prd-creator           →  Product requirements (Large scale)
     ↓
+codebase-analyzer     →  Existing codebase facts + focus areas
+    ↓
 technical-designer    →  ADR + Design Doc with acceptance criteria
     ↓
-document-reviewer     →  Quality gate
+code-verifier         →  Design Doc vs existing code verification
+    ↓
+document-reviewer     →  Quality gate with verification evidence
     ↓
 acceptance-test-gen   →  Test skeletons from ACs
     ↓
@@ -222,6 +227,7 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 | `technical-designer` | ADR and Design Doc creation (backend) |
 | `technical-designer-frontend` | Frontend ADR and Design Doc creation (React) |
 | `ui-spec-designer` | UI Specification from PRD and optional prototype code |
+| `codebase-analyzer` | Existing codebase analysis before Design Doc creation |
 | `work-planner` | Work plan creation from Design Docs |
 | `document-reviewer` | Document consistency and approval |
 | `design-sync` | Cross-document consistency verification |

package/package.json

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