codex-workflows 0.4.0 → 0.4.2

package/.agents/skills/coding-rules/references/security-checks.md

@@ -49,12 +49,14 @@ Sources: OWASP Top 10:2025, DryRun Agentic Coding Security Report (2026-03)
 - Endpoints or route handlers defined without authentication middleware
 - Resource access operations (read, update, delete) without authorization verification
 - Administrative or destructive operations accessible without elevated permissions
-- Recent research indicates this pattern appears at elevated rates in AI-generated code — treat as high-priority review target
+- AI-generated code frequently omits authentication middleware and authorization checks; treat every route handler and resource access operation as an explicit verification target during review
+- Detection approach: search for route or endpoint handlers without authentication middleware, and resource operations (read, update, delete) without authorization checks in the call chain
 
 ### Mishandling of Exceptional Conditions (OWASP A10:2025)
 - Error handlers that expose internal system details (stack traces, database errors, file paths) in responses
-- Error handlers that fail open (grant access or skip validation on error)
+- Error handlers that grant access, skip authentication, or bypass authorization when an exception occurs
 - Missing error handling on security-critical operations (authentication, authorization, cryptographic operations)
+- Detection approach: search for catch or error-handler blocks that return stack traces, database errors, or file paths in responses, and for handlers that continue with success-path behavior without re-validating security state
 
 ### Software Supply Chain Patterns (OWASP A03:2025)
 - Dependencies imported without version pinning

package/.agents/skills/coding-rules/references/typescript.md

@@ -7,13 +7,13 @@
 
 ## Comment Writing Rules
 - **Function Description Focus**: Describe what the code "does"
-- **No Historical Information**: Do not record development history
+- **History in Version Control**: Record development history in commits and PRs instead of code comments
 - **Timeless**: Write only content that remains valid whenever read
 - **Conciseness**: Keep explanations to necessary minimum
 
 ## Type Safety
 
-**Absolute Rule**: any type is completely prohibited. It disables type checking and becomes a source of runtime errors.
+**Absolute Rule**: Use `unknown`, generics, unions, intersections, or validated assertions instead of `any`. `any` disables type checking and becomes a source of runtime errors.
 
 **any Type Alternatives (Priority Order)**
 1. **unknown Type + Type Guards**: Use for validating external input (API responses, localStorage, URL parameters)
@@ -91,7 +91,7 @@ setUsers(users)
 
 **Props Design (Props-driven Approach)**
 - Props are the interface: Define all necessary information as props
-- Avoid implicit dependencies: Do not depend on global state or context without necessity
+- Declare dependencies explicitly through props, hooks, or injected modules instead of relying on ambient global state
 - Type-safe: Always define Props type explicitly
 
 **Environment Variables**
@@ -146,7 +146,7 @@ const response = await fetch('/api/data') // Backend handles API key authenticat
 
 ## Error Handling
 
-**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
+**Absolute Rule**: Handle every error explicitly with log output, recovery logic, or escalation appropriate to the failure mode.
 
 **Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
 ```typescript

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

@@ -53,34 +53,52 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### PRD (Product Requirements Document)
 **Purpose**: Define business requirements and user value
-**Includes**: Business requirements, success metrics, user stories, MoSCoW prioritization, MVP/Future phase separation, user journey diagram, scope boundary diagram
-**Excludes**: Technical implementation details, technical selection rationale, implementation phases, task breakdown
+**Scope**: Business requirements, user value, success metrics, user stories, MoSCoW prioritization, MVP/Future phase separation, user journey diagram, and scope boundary diagram only. Technical implementation details belong in Design Doc, technical decision rationale in ADR, and implementation phases or task breakdown belong in Work Plan.
 
 ### ADR (Architecture Decision Record)
 **Purpose**: Record technical decision rationale and background
-**Includes**: Decision, rationale, option comparison (minimum 3 options), architecture impact, principled implementation guidelines
-**Excludes**: Implementation schedule, detailed procedures, specific code examples, resource assignments
+**Scope**: Decision, rationale, option comparison (minimum 3 options), architecture impact, and principled implementation guidance only. Implementation procedures and code examples belong in Design Doc, while schedule and resource assignments belong in Work Plan.
 
 ### 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 (generated by acceptance-test-generator), implementation schedule
+**Scope**: Screen list and transitions, component state x display matrix, component decomposition, interaction definitions, AC traceability, existing component reuse map, visual acceptance criteria, and accessibility requirements only. Technical implementation and API contracts belong in Design Doc, test implementation belongs in generated test skeletons, and schedule belongs in Work Plan.
 
 ### 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), detailed test strategy and test case selection (generated by acceptance-test-generator from acceptance criteria)
+**Scope**: Existing codebase analysis, technical approach, dependencies and constraints, interface and contract definitions, data flow, acceptance criteria, change impact map, code inspection evidence, and verification strategy only. Technology selection rationale belongs in ADR, schedule and assignments belong in Work Plan, and detailed test strategy or case selection belongs in generated test skeletons.
+
+**Required Structural Elements**:
+- Existing codebase analysis and code inspection evidence
+- Technical approach and implementation approach decision
+- Change impact map and interface/contract definitions
+- Applicable standards with explicit/implicit classification
+- Verification Strategy
+  - Correctness proof method
+  - Early verification point
+  - Minimal form allowed for low-risk or self-evident changes: concise entries or explicit `N/A` with rationale
+    Low-risk: changes affecting 1-2 files with no external contract, integration, or data-flow changes
+    Self-evident: internal-only refactoring with identical observable inputs and outputs
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**Includes**: Task breakdown, schedule estimates, test skeleton file paths, Phase 4 Quality Assurance Phase (required), progress records
-**Excludes**: Technical rationale, design details
+**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
 
 **Phase Division Criteria**:
+
+**When Vertical Slice is selected**:
+- Each phase represents one value unit and includes its own implementation and verification
+- The earliest phase should contain the early verification point when defined
+- Final phase is always Quality Assurance
+
+**When Horizontal Slice is selected**:
 1. **Phase 1: Foundation Implementation** - Contract definitions, interfaces, test preparation
 2. **Phase 2: Core Feature Implementation** - Business logic, unit tests
 3. **Phase 3: Integration Implementation** - External connections, presentation layer
-4. **Phase 4: Quality Assurance (Required)** - Acceptance criteria, all tests, quality checks
+4. **Final Phase: Quality Assurance (Required)** - Acceptance criteria, all tests, quality checks
+
+**When Hybrid is selected**:
+- Combine vertical and horizontal phase structures as defined in the Design Doc
+- Final phase is always Quality Assurance with acceptance criteria verification, all tests passing, and quality checks complete
 
 ## Creation Process [MANDATORY]
 

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

@@ -2,7 +2,7 @@
 
 ## Status
 
-[Proposed | Accepted | Deprecated | Superseded]
+[Proposed | Accepted | Deprecated | Superseded | Rejected]
 
 ## Context
 
@@ -54,6 +54,10 @@
 
 - [List changes that are neither good nor bad]
 
+## Architecture Impact
+
+[Describe how this decision affects existing architecture: components changed, dependencies introduced or removed, and new architectural constraints]
+
 ## Implementation Guidance
 
 [Principled direction only. Implementation procedures go to Design Doc]

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

@@ -219,6 +219,28 @@ Invariants:
 |-------|----------|--------|--------|
 | [field name] | [Component A to B] | preserved / transformed / dropped | [logic or reason] |
 
+## Verification Strategy
+
+Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 (from implementation-approach) define task-level verification depth at execution time.
+Use the minimal form only when the change is low-risk or the verification path is self-evident. Otherwise fill all fields concretely.
+Low-risk: changes affecting 1-2 files with no external contract, integration, or data-flow changes.
+Self-evident: internal-only refactoring with identical observable inputs and outputs.
+
+### Correctness Proof Method
+
+- **Correctness definition**: [What "correct" means for this change]
+- **Target comparison**: [What is being compared or validated against what]
+- **Verification method**: [How correctness will be verified]
+- **Observable success indicator**: [What observable result proves the verification succeeded]
+- **Verification timing**: [`phase_1` | `per_phase` | `integration_phase` | `final_phase`]
+- **Timing note**: [Optional free-text clarification when the enum alone is insufficient]
+
+### Early Verification Point
+
+- **First verification target**: [The smallest unit that proves the approach works]
+- **Success criteria**: [Observable outcome that proves correctness]
+- **Failure response**: [What to do if early verification fails]
+
 ### State Transitions and Invariants (When Applicable)
 
 ```yaml
@@ -255,11 +277,16 @@ System Invariants:
 
 ### Error Handling
 
-[Types of errors and how to handle them]
+| Error Category | Example | Detection | Recovery Strategy | User Impact |
+|---------------|---------|-----------|-------------------|-------------|
+| [Validation / External / Infrastructure / Business logic] | [Specific error] | [How detected] | [Retry / Fallback / Propagate / Log-and-continue] | [User-facing message or silent handling] |
 
 ### Logging and Monitoring
 
-[What to record in logs and how to monitor]
+- **Log events**: [Key events to log: state transitions, external calls, error occurrences, performance thresholds]
+- **Log levels**: [Which events use DEBUG / INFO / WARN / ERROR]
+- **Sensitive data**: [Fields to mask or exclude; align with Security Considerations]
+- **Monitoring**: [Metrics to track, alert thresholds, dashboard requirements]
 
 ## Implementation Plan
 
@@ -279,12 +306,6 @@ System Invariants:
    - Technical Reason: [Technical necessity to implement after A]
    - Prerequisites: [Required pre-implementations]
 
-### Integration Points
-
-**Integration Point 1: [Name]**
-- Components: [Component A] to [Component B]
-- Contract: [Interface/API contract between components]
-
 ### Migration Strategy
 
 [Technical migration approach, ensuring backward compatibility]
@@ -301,7 +322,9 @@ Mark items as N/A with brief rationale when the feature has no relevant trust bo
 
 ## Future Extensibility
 
-[Considerations for future feature additions or changes]
+- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use]
+- **Known future requirements**: [Planned features that influenced current design decisions]
+- **Intentional limitations**: [What was deliberately kept simple and why]
 
 ## Alternative Solutions
 

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

@@ -13,6 +13,25 @@ Related Issue/PR: #XXX (if any)
 - ADR: [docs/adr/ADR-XXXX.md] (if any)
 - PRD: [docs/prd/XXX.md] (if any)
 
+## Verification Strategies (from Design Docs)
+
+Repeat this block for each Design Doc when multiple Design Docs exist. Preserve each strategy's identity and source document path. Merge strategies only when the Design Docs explicitly define a shared one.
+
+### Verification Strategy: [docs/design/XXX.md]
+
+#### Correctness Proof Method
+- **Correctness definition**: [extracted from Design Doc]
+- **Target comparison**: [extracted from Design Doc]
+- **Verification method**: [extracted from Design Doc]
+- **Observable success indicator**: [extracted from Design Doc]
+- **Verification timing**: [`phase_1` | `per_phase` | `integration_phase` | `final_phase`]
+- **Timing note**: [optional clarification]
+
+#### Early Verification Point
+- **First verification target**: [extracted from Design Doc]
+- **Success criteria**: [extracted from Design Doc]
+- **Failure response**: [extracted from Design Doc]
+
 ## Objective
 [Why this change is necessary, what problem it solves]
 
@@ -33,10 +52,46 @@ Related Issue/PR: #XXX (if any)
 
 ## Implementation Phases
 
-(Note: Phase structure is determined based on Design Doc technical dependencies and implementation approach)
+Select one phase structure based on the implementation approach from the Design Doc.
+Delete every unused option before finalizing the work plan. The final document must contain only the selected phase structure.
+
+### Option A: Vertical Slice Phase Structure
 
-### Phase 1: [Phase Name] (Estimated commits: X)
-**Purpose**: [What this phase aims to achieve]
+Use when implementation approach is Vertical Slice. Each phase represents one value unit and includes its own verification.
+
+### Phase 1: [Value Unit 1] (Estimated commits: X)
+**Purpose**: [First slice that proves the approach works]
+**Verification**: [Use the early verification point when applicable]
+
+#### Tasks
+- [ ] Task 1: Specific work content
+- [ ] Task 2: Verification for this value unit
+- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+
+#### Phase Completion Criteria
+- [ ] Early verification point passed
+- [ ] [Functional completion criteria]
+- [ ] [Quality completion criteria]
+
+### Phase 2: [Value Unit 2] (Estimated commits: X)
+**Purpose**: [Subsequent slice]
+**Verification**: [Verification for this value unit]
+
+#### Tasks
+- [ ] Task 1: Specific work content
+- [ ] Task 2: Verification for this value unit
+- [ ] Quality check
+
+#### Phase Completion Criteria
+- [ ] [Functional completion criteria]
+- [ ] [Quality completion criteria]
+
+### Option B: Horizontal Slice Phase Structure
+
+Use when implementation approach is Horizontal Slice. Phases follow Foundation -> Core -> Integration -> QA.
+
+### Phase 1: [Foundation] (Estimated commits: X)
+**Purpose**: Contract definitions, interfaces, test preparation
 
 #### Tasks
 - [ ] Task 1: Specific work content
@@ -48,26 +103,26 @@ Related Issue/PR: #XXX (if any)
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
 
-### Phase 2: [Phase Name] (Estimated commits: X)
-**Purpose**: [What this phase aims to achieve]
+### Phase 2: [Core Feature] (Estimated commits: X)
+**Purpose**: Business logic, unit tests
 
 #### Tasks
 - [ ] Task 1: Specific work content
 - [ ] Task 2: Specific work content
-- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Quality check
 - [ ] Integration tests: Verify overall feature functionality
 
 #### Phase Completion Criteria
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
 
-### Phase 3: [Phase Name] (Estimated commits: X)
-**Purpose**: [What this phase aims to achieve]
+### Phase 3: [Integration] (Estimated commits: X)
+**Purpose**: External connections, presentation layer
 
 #### Tasks
 - [ ] Task 1: Specific work content
 - [ ] Task 2: Specific work content
-- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Quality check
 - [ ] Integration tests: Verify component coordination
 
 #### Phase Completion Criteria
@@ -75,7 +130,9 @@ Related Issue/PR: #XXX (if any)
 - [ ] [Quality completion criteria]
 
 ### Final Phase: Quality Assurance (Required) (Estimated commits: 1)
-**Purpose**: Overall quality assurance and Design Doc consistency verification
+This phase is required for all implementation approaches.
+
+**Purpose**: Cross-cutting quality assurance and Design Doc consistency verification
 
 #### Tasks
 - [ ] Verify all Design Doc acceptance criteria achieved

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

@@ -37,9 +37,16 @@ Brief observations recorded after reading Investigation Targets:
 - [ ] Improve code (maintain passing tests)
 - [ ] Confirm added tests still pass
 
+## Operation Verification Methods
+(Derived from Verification Strategy in the work plan)
+- **Verification method**: [What to verify and how]
+- **Success criteria**: [Observable outcome that proves correctness]
+- **Failure response**: [What to do if verification fails]
+- **Verification level**: [L1/L2/L3, per implementation-approach skill]
+
 ## Completion Criteria
 - [ ] All added tests pass
-- [ ] Operation verified (select L1/L2/L3, per implementation-approach skill)
+- [ ] Operation verified per Operation Verification Methods above
 - [ ] Deliverables created (for research/design tasks)
 
 ## Notes

package/.agents/skills/recipe-build/SKILL.md

@@ -90,7 +90,7 @@ ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent wo
 **MANDATORY suffix for ALL sub-agent prompts**:
 ```
 [SYSTEM CONSTRAINT]
-This agent operates within build skill scope. Use orchestrator-provided rules only.
+This agent operates within build skill scope. Use the task file as the primary instruction source. Use the active Design Doc or work plan only as supporting context when the task file references them. Constraints explicitly passed in this prompt by the orchestrator take precedence over supporting context. The agent's own role contract and required quality rules remain in force.
 ```
 
 Autonomous sub-agents require scope constraints for stable execution. MUST append this constraint to every sub-agent prompt.

package/.agents/skills/recipe-design/SKILL.md

@@ -17,8 +17,9 @@ description: "Execute from requirement analysis to design document creation."
 
 **Execution Protocol**:
 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
-2. **Follow subagents-orchestration-guide skill design flow exactly**:
-   - Execute: requirement-analyzer -> technical-designer -> document-reviewer -> design-sync
+2. **Follow the design flow defined in subagents-orchestration-guide**:
+   - Apply the scale-specific and layer-specific branches defined there, including PRD, ADR, and UI Spec steps when required
+   - Use `requirement-analyzer -> codebase-analyzer -> technical-designer -> code-verifier -> document-reviewer -> design-sync` as the core design-document path after prerequisite branches are resolved
    - **[STOP — BLOCKING]** At every `[Stop: ...]` marker -> Present status to user for confirmation. **CANNOT proceed until user explicitly confirms.**
 3. **Scope**: Complete when design documents receive approval
 
@@ -27,10 +28,14 @@ ENFORCEMENT: Skipping any quality gate invalidates the design output.
 
 ## Workflow Overview
 
+Core design-document path after prerequisite branches such as PRD, ADR, or UI Spec are resolved:
+
 ```
 Requirements -> requirement-analyzer -> [Stop: Scale determination]
                                              |
-                                     technical-designer -> document-reviewer
+                                     codebase-analyzer
+                                             |
+                                     technical-designer -> code-verifier -> document-reviewer
                                              |
                                         design-sync -> [Stop: Design approval]
 ```
@@ -48,12 +53,7 @@ Requirements -> requirement-analyzer -> [Stop: Scale determination]
 
 Requirements: $ARGUMENTS
 
-Considering the deep impact on design, first engage in dialogue to understand the background and purpose of requirements:
-- What problems do you want to solve?
-- Expected outcomes and success criteria
-- Relationship with existing systems
-
-Once requirements are moderately clarified, analyze with requirement-analyzer and create appropriate design documents according to scale.
+Pass the user requirements directly to requirement-analyzer as the first action. If clarification is needed, handle it at the requirement-analysis stop point before proceeding.
 
 MUST clearly present design alternatives and trade-offs.
 
@@ -64,13 +64,19 @@ Execute the process below within design scope.
 ### Step 1: Requirement Analysis
 Spawn requirement-analyzer agent: "Analyze the following requirements and determine scale: $ARGUMENTS"
 
-### Step 2: Design Document Creation
-Spawn technical-designer agent: "Create design document based on requirement analysis output. Include architecture decisions, component design, and acceptance criteria."
+### Step 2: Codebase Analysis
+Spawn codebase-analyzer agent: "Analyze the existing codebase to provide evidence for Design Doc creation. requirement_analysis: [output from Step 1]. requirements: $ARGUMENTS"
+
+### Step 3: Design Document Creation
+Spawn technical-designer agent: "Create design document based on requirement analysis output and codebase analysis output. Include architecture decisions, component design, and acceptance criteria."
+
+### Step 4: Code Verification
+Spawn code-verifier agent: "Verify the design document against the current codebase. document_path: [output from Step 3]. doc_type: design-doc."
 
-### Step 3: Document Review
-Spawn document-reviewer agent: "Review the design document created in the previous step. Verify completeness, consistency, and quality."
+### Step 5: Document Review
+Spawn document-reviewer agent: "Review the design document created in the previous step. Verify completeness, consistency, and quality. code_verification: [output from Step 4]"
 
-### Step 4: Consistency Verification
+### Step 6: Consistency Verification
 Spawn design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints."
 
 **Note**: design-sync returns `sync_status: "SKIPPED"` when only 1 Design Doc exists. This is distinct from `NO_CONFLICTS` and MUST be reported as such to the user.
@@ -78,7 +84,9 @@ Spawn design-sync agent: "Verify consistency of the design document with other e
 ## Completion Criteria
 
 - [ ] Spawned requirement-analyzer and determined scale
+- [ ] Spawned codebase-analyzer and passed its findings into design creation
 - [ ] Created appropriate design document (ADR or Design Doc) via technical-designer
+- [ ] Spawned code-verifier and passed its findings into document review
 - [ ] Spawned document-reviewer and addressed feedback
 - [ ] Spawned design-sync for consistency verification
 - [ ] Obtained user approval for design document

package/.agents/skills/recipe-front-build/SKILL.md

@@ -98,7 +98,7 @@ ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent wo
 **MANDATORY suffix for ALL sub-agent prompts**:
 ```
 [SYSTEM CONSTRAINT]
-This agent operates within build skill scope. Use orchestrator-provided rules only.
+This agent operates within build skill scope. Use the task file as the primary instruction source. Use the active Design Doc or work plan only as supporting context when the task file references them. Constraints explicitly passed in this prompt by the orchestrator take precedence over supporting context. The agent's own role contract and required quality rules remain in force.
 ```
 
 Autonomous sub-agents require scope constraints for stable execution. MUST append this constraint to every sub-agent prompt.

package/.agents/skills/recipe-fullstack-build/SKILL.md

@@ -108,7 +108,7 @@ ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent wo
 **MANDATORY suffix for ALL sub-agent prompts**:
 ```
 [SYSTEM CONSTRAINT]
-This agent operates within build skill scope. Use orchestrator-provided rules only.
+This agent operates within build skill scope. Use the task file as the primary instruction source. Use the active Design Docs or work plan only as supporting context when the task file references them. Constraints explicitly passed in this prompt by the orchestrator take precedence over supporting context. The agent's own role contract and required quality rules remain in force.
 ```
 
 Autonomous sub-agents require scope constraints for stable execution. MUST append this constraint to every sub-agent prompt.

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

@@ -7,9 +7,7 @@ description: "Guides subagent coordination through implementation workflows. Use
 
 ## Role: The Orchestrator
 
-**The orchestrator coordinates subagents like a conductor -- directing the musicians without playing the instruments.**
-
-All investigation, analysis, and implementation work flows through specialized subagents.
+The orchestrator coordinates subagents. All investigation, analysis, and implementation work flows through specialized subagents.
 
 ### Prompt Construction Rule
 Every subagent prompt must include:
@@ -317,18 +315,11 @@ Stop autonomous execution and escalate to user in the following cases:
 3. **Work-planner update restriction violated**: Requirement changes after task-decomposer starts require overall redesign
 4. **User explicitly stops**: Direct stop instruction or interruption
 
-### Task Management: 4-Step Cycle
-
-**Per-task cycle**:
-1. task-executor: Implementation
-2. Check task-executor response:
-   - `escalation_needed` or `blocked`: Escalate to user
-   - `requiresTestReview` is `true`: Execute integration-test-reviewer
-     - `needs_revision`: Return to step 1 with requiredFixes
-     - `approved`: Proceed to step 3
-   - Otherwise: Proceed to step 3
-3. quality-fixer: Quality check and fixes
-4. git commit (on `status: "approved"`)
+Use the task loop defined in the autonomous execution diagram above. The canonical per-task cycle is:
+1. task-executor implementation
+2. escalation or integration-test-reviewer decision
+3. quality-fixer quality gate
+4. git commit on approval
 
 ## Main Orchestrator Roles
 
@@ -359,13 +350,27 @@ Stop autonomous execution and escalate to user in the following cases:
 
 **On error**: Escalate to user if files are not generated
 
+### Design Doc to Work Plan Verification Handoff
+
+When a Design Doc contains a Verification Strategy section, the orchestrator must carry forward:
+- Design Doc path
+- Verification Strategy details:
+  - Correctness definition
+  - Target comparison
+  - Verification method
+  - Observable success indicator
+  - Verification timing
+  - Early verification point (first target, success criteria, failure response)
+
+The resulting work plan must include this summary in its header so the plan remains self-sufficient for downstream task generation and execution planning.
+
 ## Important Constraints [MANDATORY]
 
 - **Quality check is REQUIRED**: quality-fixer approval MUST be obtained before commit
 - **Structured response REQUIRED**: Information transmission between subagents MUST use JSON format
 - **Approval management**: Document creation -> Execute document-reviewer -> Get user approval before proceeding
 - **Flow confirmation**: After getting approval, MUST check next step with work planning flow (large/medium/small scale)
-- **Consistency verification**: If subagent determinations contradict, MUST prioritize guidelines
+- **Consistency verification**: If subagent determinations contradict, MUST prioritize the constraints and decision rules defined in this orchestration guide
 
 **ENFORCEMENT**: Violating ANY constraint requires immediate correction
 
@@ -380,9 +385,9 @@ Stop autonomous execution and escalate to user in the following cases:
 
 When receiving a task, check the following:
 
-- [ ] Confirmed if there is an orchestrator instruction
+- [ ] Confirmed whether the user provided a specific workflow recipe or explicit execution constraint
 - [ ] Determined task type (new feature/fix/research, etc.)
-- [ ] Considered appropriate subagent utilization
+- [ ] Selected the next subagent according to the decision flow and current phase
 - [ ] Decided next action according to decision flow
 - [ ] Monitored requirement changes and errors during autonomous execution mode
 

package/.agents/skills/testing/SKILL.md

@@ -64,7 +64,7 @@ All tests MUST be:
 
 - **Independent**: No dependencies between tests
 - **Reproducible**: Same input always produces same output
-- **Fast**: Complete test suite runs in reasonable time
+- **Fast**: Complete the full test suite within the project's accepted feedback window and flag suites that materially slow local iteration or CI
 - **Self-checking**: Clear pass/fail without manual verification
 - **Timely**: Written close to the code they test
 
@@ -162,7 +162,7 @@ Test names should clearly describe:
 
 - Use setup hooks to prepare test environment
 - Use teardown hooks to clean up resources
-- Keep setup minimal and focused
+- Keep setup scoped to the data, dependencies, and fixtures required for the behavior under test
 - Ensure teardown runs even if test fails
 
 ## Mocking and Test Doubles
@@ -177,7 +177,7 @@ Test names should clearly describe:
 ### Mocking Principles [MANDATORY]
 
 - Mock at boundaries, not internally — use real implementations for internal utilities
-- Keep mocks simple and focused
+- Keep each mock limited to the behavior the test needs to control or observe
 - Verify mock expectations when relevant
 - Use adapters for external libraries/frameworks you do not control
 
@@ -345,7 +345,7 @@ Eliminate tests that fail intermittently:
 - Add test for every bug fix
 - Maintain comprehensive test suite
 - Run full suite regularly
-- Don't delete tests without good reason
+- Delete a test only when the covered behavior no longer exists or the same behavior is covered by a stronger test at the correct level
 
 ### Legacy Code
 

package/.codex/agents/acceptance-test-generator.toml

@@ -242,7 +242,8 @@ These annotations are used when planning and prioritizing test implementation.
 ## Constraints and Quality Standards
 
 **Mandatory Compliance**:
-- Output only test skeletons (prohibit implementation code, assertions, mocks)
+- Output test skeletons only: verification points, expected results, and pass criteria
+- Downstream consumers treat these skeletons as design artifacts rather than runnable tests
 - Clearly state verification points, expected results, and pass criteria for each test
 - Preserve original AC statements in comments (ensure traceability)
 - Stay within test budget; report if budget insufficient for critical tests
@@ -273,7 +274,7 @@ These annotations are used when planning and prioritizing test implementation.
 - Framework/Language: Auto-detect from existing test files
 - Placement: Identify test directory with project-specific patterns
 - Naming: Follow existing file naming conventions
-- Output: Test skeleton only (exclude implementation code)
+- Output: Test skeletons only (follow Constraints and Quality Standards for the boundary)
 
 **File Operations**:
 - Existing files: Append to end, prevent duplication (check existing tests)

package/.codex/agents/document-reviewer.toml

@@ -97,6 +97,7 @@ For DesignDoc, additionally verify:
 - [ ] Dependencies described as existing have verification results or authoritative external source
 - [ ] Field propagation map present (when fields cross boundaries)
 - [ ] Data-oriented designs contain concrete data design or Test Boundaries content, or an explicit N/A rationale
+- [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -114,6 +115,7 @@ For DesignDoc, additionally verify:
 - **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
 - **Data design completeness check**: When the document references persistence, storage, database, repository, query, ORM, migration, table, schema, or column concepts, verify that the Design Doc includes concrete data design content or an explicit N/A rationale. Useful evidence includes schema references, data model notes, or Test Boundaries with data layer strategy
 - **Code-verifier evidence integration**: When `code_verification` is provided, reconcile major or critical discrepancies and undocumented data operations as part of Gate 1 completeness and consistency review
+- **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase
 - **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
 
 **Perspective-specific Mode**:
@@ -255,6 +257,8 @@ Include in output when `prior_context_count > 0`:
 
 - [ ] Match of requirements, terminology, numbers between documents
 - [ ] Completeness of required elements in each document
+- [ ] Verification Strategy present with a concrete correctness definition and early verification point
+- [ ] Verification Strategy aligns with design type and implementation approach
 - [ ] Compliance with project rules
 - [ ] Technical feasibility and reasonableness of estimates
 - [ ] Clarification of risks and countermeasures

package/.codex/agents/requirement-analyzer.toml

@@ -55,7 +55,7 @@ Scale determination and required document details follow the principles in docum
 - **Medium**: 3-5 files, spanning multiple components
 - **Large**: 6+ files, architecture-level changes
 
-※ADR conditions (contract system changes, data flow changes, architecture changes, external dependency changes) require ADR regardless of scale
+Note: ADR conditions (contract system changes, data flow changes, architecture changes, external dependency changes) require ADR regardless of scale
 
 ### Important: Clear Determination Expressions
 MUST use the following expressions to show clear determinations:
@@ -162,7 +162,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 - [ ] Do I understand the user's true purpose?
 - [ ] Have I properly estimated the impact scope?
 - [ ] Have I correctly determined ADR necessity?
-- [ ] Have I not overlooked technical risks?
+- [ ] Have I identified all technical risks and dependencies?
 - [ ] Have I listed scopeDependencies for uncertain scale?
 - [ ] Final response is the JSON output
 

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/task-executor.toml

@@ -162,7 +162,7 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 **Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`
 
 #### Pre-implementation Verification (Pattern 5 Compliant)
-1. **Read relevant Design Doc sections** and understand accurately
+1. **Read relevant Design Doc sections** and extract interface contracts, data structures, dependency constraints, and verification expectations
 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility
 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

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

@@ -80,7 +80,7 @@ Must be performed before Design Doc creation:
    - Search existing code for keywords related to planned component
    - Look for components with same domain, responsibilities, or UI patterns
    - Decision and action:
-     - Similar component found → Use that component (do not create new component)
+     - Similar component found → Reuse, compose, or extend that component path and document the reuse decision
      - Similar component is technical debt → Create ADR improvement proposal before implementation
      - No similar component → Proceed with new implementation
 
@@ -146,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:
 
@@ -265,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

@@ -97,7 +97,7 @@ Must be performed before Design Doc creation:
    - Search existing code for keywords related to planned functionality
    - Look for implementations with same domain, responsibilities, or configuration patterns
    - Decision and action:
-     - Similar functionality found → Use that implementation (do not create new implementation)
+     - Similar functionality found → Reuse or extend that implementation path and document the reuse decision
      - Similar functionality is technical debt → Create ADR improvement proposal before implementation
      - No similar functionality → Proceed with new implementation
 
@@ -180,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:
 
@@ -340,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).
@@ -100,7 +111,7 @@ Execute file output immediately. Final approval is managed by the orchestrator r
 1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies
 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase
 3. **Risk Management**: List risks and countermeasures in advance, define detection methods
-4. **Ensure Flexibility**: Prioritize essential purpose, avoid excessive detail
+4. **Ensure Flexibility**: Prioritize essential purpose and include only details required for task execution, verification, and dependency management
 5. **Design Doc Compliance**: All task completion criteria derived from Design Doc specifications
 6. **Implementation Pattern Consistency**: When including implementation samples, MUST ensure strict compliance with Design Doc implementation approach
 
@@ -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/package.json

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