codex-workflows 0.4.4 → 0.4.5

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

@@ -81,7 +81,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**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.
+**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, Design-to-Plan Traceability mapping for implementation-relevant technical requirements, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
 
 **Phase Division Criteria**:
 

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

@@ -137,6 +137,14 @@ No Ripple Effect:
   - [Explicitly specify unaffected features]
 ```
 
+### Interface Change Impact Analysis
+
+Use this table for interface or contract compatibility decisions. Record what changes at the boundary and how compatibility is preserved.
+
+| Existing Interface | New Interface | Conversion Required | Adapter / Wrapper Required | Compatibility Method |
+|-------------------|---------------|---------------------|----------------------------|----------------------|
+| [Function / method / props / contract] | [Function / method / props / contract] | [Yes / No] | [Required / Not Required] | [Adapter, wrapper, migration path, deprecation policy, or `-`] |
+
 ### Architecture Overview
 
 [How this feature is positioned within the overall system]
@@ -149,9 +157,11 @@ No Ripple Effect:
 
 ### Integration Points List
 
-| Integration Point | Location | Old Implementation | New Implementation | Switching Method |
-|-------------------|----------|-------------------|-------------------|------------------|
-| Integration Point 1 | [Class/Function] | [Existing Process] | [New Process] | [DI/Factory etc.] |
+Use this table for runtime wiring, switching, or registration points. Record how the integration is connected and how the switching behavior is verified.
+
+| Integration Point | Location | Old Implementation | New Implementation | Switching Method | Verification Method |
+|-------------------|----------|-------------------|-------------------|------------------|---------------------|
+| Integration Point 1 | [Class/Function] | [Existing Process] | [New Process] | [DI/Factory etc.] | [How this switching or integration will be verified] |
 
 ### Main Components
 

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

@@ -32,6 +32,31 @@ Repeat this block for each Design Doc when multiple Design Docs exist. Preserve
 - **Success criteria**: [extracted from Design Doc]
 - **Failure response**: [extracted from Design Doc]
 
+## Design-to-Plan Traceability
+
+Map each Design Doc technical requirement to the task or phase that covers it. Use one row per extracted requirement item. Every row must have at least one covering task, or an explicit justified gap.
+
+| Source Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
+|-------------------|------------|---------|----------|--------------------|------------|-------|
+| [docs/design/xxx-design.md] | [Section name] | [Specific implementation-relevant item] | impl-target / connection-switching / contract-change / verification / prerequisite / scope-boundary | [P1-T1, P1-T2] | covered | |
+
+**Category values**: `impl-target` (implementation target), `connection-switching` (connection, switching, registration, dependency wiring), `contract-change` (interface change and propagation across boundaries), `verification` (verification method, test boundary, comparison point), `prerequisite` (migration, setup, security, environment preparation), `scope-boundary` (explicit non-target or no-ripple boundary that must remain unchanged)
+
+**Gap Status values**: `covered` (mapped to one or more tasks), `gap` (no task exists yet; include justification in Notes and require user confirmation before plan approval)
+
+**Task ID format**:
+- Implementation tasks: `P<phase-number>-T<task-number>` such as `P1-T1`, `P2-T3`
+- Phase completion tasks: `P<phase-number>-COMPLETE` such as `P1-COMPLETE`
+- Final quality task: `FINAL-QA`
+- Multiple covering tasks: comma-separated IDs in display order, for example `P1-T1, P1-T2`
+
+**DD Item normalization rules**:
+- One row = one independently plannable obligation that can be covered, deferred, or verified without relying on a hidden sub-obligation
+- Split compound obligations joined by `and`, `or`, or separate boundary crossings when they can be implemented or verified independently
+- Normalize same-boundary field propagation into one row when the fields must move together through the same boundary for the same reason
+- Merge duplicate restatements of the same obligation from multiple DD sections into one row and cite the primary section in `DD Section`
+- Keep `scope-boundary` rows concrete: name the protected file group, component boundary, contract, or workflow that must remain unchanged
+
 ## Objective
 [Why this change is necessary, what problem it solves]
 
@@ -64,27 +89,29 @@ Use when implementation approach is Vertical Slice. Each phase represents one va
 **Verification**: [Use the early verification point when applicable]
 
 #### Tasks
-- [ ] Task 1: Specific work content
-- [ ] Task 2: Verification for this value unit
+- [ ] [P1-T1] Specific work content
+- [ ] [P1-T2] 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]
+- [ ] [P1-COMPLETE] Phase completion verification recorded
 
 ### 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
+- [ ] [P2-T1] Specific work content
+- [ ] [P2-T2] Verification for this value unit
 - [ ] Quality check
 
 #### Phase Completion Criteria
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
+- [ ] [P2-COMPLETE] Phase completion verification recorded
 
 ### Option B: Horizontal Slice Phase Structure
 
@@ -94,40 +121,43 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation -
 **Purpose**: Contract definitions, interfaces, test preparation
 
 #### Tasks
-- [ ] Task 1: Specific work content
-- [ ] Task 2: Specific work content
+- [ ] [P1-T1] Specific work content
+- [ ] [P1-T2] Specific work content
 - [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
 - [ ] Unit tests: All related tests pass
 
 #### Phase Completion Criteria
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
+- [ ] [P1-COMPLETE] Phase completion verification recorded
 
 ### Phase 2: [Core Feature] (Estimated commits: X)
 **Purpose**: Business logic, unit tests
 
 #### Tasks
-- [ ] Task 1: Specific work content
-- [ ] Task 2: Specific work content
+- [ ] [P2-T1] Specific work content
+- [ ] [P2-T2] Specific work content
 - [ ] Quality check
 - [ ] Integration tests: Verify overall feature functionality
 
 #### Phase Completion Criteria
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
+- [ ] [P2-COMPLETE] Phase completion verification recorded
 
 ### Phase 3: [Integration] (Estimated commits: X)
 **Purpose**: External connections, presentation layer
 
 #### Tasks
-- [ ] Task 1: Specific work content
-- [ ] Task 2: Specific work content
+- [ ] [P3-T1] Specific work content
+- [ ] [P3-T2] Specific work content
 - [ ] Quality check
 - [ ] Integration tests: Verify component coordination
 
 #### Phase Completion Criteria
 - [ ] [Functional completion criteria]
 - [ ] [Quality completion criteria]
+- [ ] [P3-COMPLETE] Phase completion verification recorded
 
 ### Final Phase: Quality Assurance (Required) (Estimated commits: 1)
 This phase is required for all implementation approaches.
@@ -135,7 +165,7 @@ 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
+- [ ] [FINAL-QA] 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 (including integration/E2E from test skeletons, when provided)

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

@@ -375,6 +375,10 @@ When a Design Doc contains a Verification Strategy section, the orchestrator mus
 The resulting work plan must include this summary in its header so the plan remains self-sufficient for downstream task generation and execution planning.
 When the Design Doc includes an `Output Comparison` section, carry forward the comparison input, expected output fields or format, diff method, and transformation pipeline coverage as part of that summary.
 
+In addition, the orchestrator must preserve implementation-relevant technical requirements from each Design Doc so work-planner can create a Design-to-Plan Traceability table. Use the category values and normalization rules defined in the plan template, including protected no-change boundaries from sections such as `No Ripple Effect`.
+
+Work-planner maps each extracted item to a covering task or phase. If no covering task exists, the row is marked `gap` with justification. Justified gaps require user confirmation before plan approval.
+
 ## Important Constraints [MANDATORY]
 
 - **Quality check is REQUIRED**: quality-fixer approval MUST be obtained before commit

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

@@ -52,6 +52,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Grasp completion criteria and quality standards
    - **Interface change detection and response**
    - **Extract Verification Strategy from the work plan header**
+   - **Read Design-to-Plan Traceability and preserve its coverage in generated tasks**
 
 2. **Task Decomposition**
    - Decompose at 1 commit = 1 task granularity (logical change unit)
@@ -89,6 +90,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Confirm phase structure
    - Extract task list
    - Identify dependencies
+   - Read Design-to-Plan Traceability rows and verify every `covered` item has a corresponding generated task or phase completion task
    - **Overall Optimization Considerations**
      - Identify common processing (prevent redundant implementation)
      - Pre-map impact scope
@@ -159,6 +161,17 @@ When the work plan includes one or more Verification Strategy blocks:
 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.
 
+## Design-to-Plan Traceability Propagation
+
+When the work plan includes a `Design-to-Plan Traceability` section:
+
+1. **Coverage preservation**: Ensure every row marked `covered` is represented by at least one generated task file or phase completion task.
+2. **Gap handling**: Preserve each `gap` row as a planning issue and surface it to the caller when task generation would otherwise assume missing design details.
+3. **Boundary integrity**: For `contract-change` and `connection-switching` rows, include every affected boundary, adapter, wrapper, or wiring point in the generated task scope.
+4. **Scope-boundary integrity**: For `scope-boundary` rows, include explicit no-change notes, protected file groups, or verification steps that keep the protected boundary out of scope.
+5. **Verification integrity**: For `verification` rows, ensure the corresponding task file includes the required comparison or verification method in Operation Verification Methods.
+6. **Prerequisite integrity**: For `prerequisite` rows, place setup, migration, seed, auth, or environment work before dependent implementation tasks.
+
 ## Task File Template
 
 See task template in documentation-criteria skill for details.

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

@@ -42,7 +42,8 @@ Skill Status:
 4. Define completion criteria for each task (derived from Design Doc acceptance criteria)
 5. Place test implementation and execution appropriately for each phase
 6. Concretize risks and countermeasures
-7. Document in progress-trackable format
+7. Create explicit Design-to-Plan Traceability so Design Doc technical requirements are covered without silent omission
+8. Document in progress-trackable format
 
 ## Input Parameters
 
@@ -62,6 +63,10 @@ Read the Design Doc(s), UI Spec, PRD, and ADR (if provided). Extract:
 - 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
+- Implementation-relevant technical requirements from each Design Doc section using the category values defined in the plan template's `Design-to-Plan Traceability` section
+
+Focus on implementation-relevant items only: items that directly inform task creation, dependency ordering, verification design, or protected no-change boundaries.
+Extract `scope-boundary` rows from explicit non-target statements such as `No Ripple Effect`, compatibility constraints, or protected boundaries that must remain unchanged.
 
 ### 2. Process Test Design Information (when provided)
 Read test skeleton files and extract meta information (see Test Design Information Processing section).
@@ -86,10 +91,30 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati
 - 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
+### 5. Build Design-to-Plan Traceability
+Create a Design-to-Plan Traceability table before finalizing tasks.
+
+For each extracted technical requirement item:
+- Record source Design Doc path and section name
+- Normalize the item according to the plan template's DD Item normalization rules
+- Map the item to one or more covering task IDs or phase completion task IDs using the plan template's Task ID format
+- Mark `covered` when a concrete task covers the item
+- Mark `gap` only when no concrete task covers the item yet
+- Add justification in Notes for every `gap`
+
+Traceability rules:
+- A broader implementation task may cover multiple DD items when the mapping remains explicit
+- Acceptance criteria alone are insufficient coverage when the DD also specifies interface changes, dependency wiring, verification boundaries, or prerequisite work
+- Verification Strategy items may map to dedicated verification tasks or phase completion tasks, but the mapping must be explicit
+- Interface change and field propagation items must map to the task that updates every affected boundary or compatibility layer
+- Scope boundaries must map to the task IDs or phase completion task IDs that verify the protected boundary remains unchanged
+- Any `gap` without justification is an error
+- Any justified `gap` must be flagged for user confirmation before plan approval
+
+### 6. Define Tasks with Completion Criteria
 For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete).
 
-### 6. Produce Work Plan Document
+### 7. Produce Work Plan Document
 Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid).
 
 ## Work Plan Output Format
@@ -248,10 +273,17 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 
 - [ ] Design Doc(s) consistency verification
 - [ ] Verification Strategies extracted from each Design Doc and included in the plan header without unintended merging
+- [ ] Design-to-Plan Traceability table completed for all extracted implementation-relevant DD items
+  - [ ] Every row mapped to covering task(s) or justified `gap`
+  - [ ] Interface change and propagation items mapped explicitly
+  - [ ] Connection, switching, and prerequisite items mapped explicitly
+  - [ ] Scope-boundary items mapped explicitly when the Design Doc defines protected no-change areas
+  - [ ] Covered By Task(s) uses only normalized task IDs
+  - [ ] No unjustified `gap` entries remain
 - [ ] 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
+- [ ] Acceptance criteria and extracted technical requirements converted to tasks or justified gaps
 - [ ] Quality assurance exists in final phase
 - [ ] Test skeleton file paths listed in corresponding phases (when provided)
 - [ ] E2E environment prerequisites addressed when E2E skeletons are provided

package/package.json

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