codex-workflows 0.4.3 → 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
 
@@ -241,6 +251,15 @@ Self-evident: internal-only refactoring with identical observable inputs and out
 - **Success criteria**: [Observable outcome that proves correctness]
 - **Failure response**: [What to do if early verification fails]
 
+### Output Comparison (When Changing Existing Observable Behavior, an External Contract, or a Persisted Data Shape)
+
+- **Comparison input**: [Identical input used for both the current and new implementation]
+- **Expected output fields**: [Specific fields, columns, or output format to compare]
+- **Diff method**: [How the outputs are compared, such as field-by-field diff, file diff, or snapshot comparison]
+- **Transformation pipeline coverage**: [Map each listed step from codebase analysis `dataTransformationPipelines` to the comparison that verifies its output. If a step passes data through unchanged, mark it excluded with rationale]
+
+Mark as `N/A` with a brief rationale only when the change does not alter existing observable behavior, an external contract, or a persisted data shape.
+
 ### State Transitions and Invariants (When Applicable)
 
 ```yaml

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

@@ -252,7 +252,7 @@ When receiving new features or change requests, start with requirement-analyzer.
 ### Design Flow Data Passing
 
 - Pass requirement-analyzer output and original requirements to codebase-analyzer
-- Pass codebase-analyzer JSON to technical-designer or technical-designer-frontend as `Codebase Analysis`
+- Pass codebase-analyzer JSON to technical-designer or technical-designer-frontend as `Codebase Analysis`, including `dataTransformationPipelines` when present
 - Pass Design Doc path to code-verifier
 - Pass code-verifier JSON to document-reviewer as `code_verification`
 
@@ -373,6 +373,11 @@ When a Design Doc contains a Verification Strategy section, the orchestrator mus
   - 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.
+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]
 

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

@@ -70,14 +70,29 @@ Identify what exists, what appears missing, and what deserves close attention in
 ### Step 2: Existing Code Element Discovery
 
 For each affected file or inferred target file in the selected scope:
-1. Read the file and record public interfaces, key functions, classes, types, constants, and configuration use
-2. Trace one level of direct dependencies through imports or equivalent declarations
-3. Search for patterns related to:
+1. Read the file in full and record:
+   - public and private/internal interfaces, key functions, methods, classes, types, constants, and configuration use
+   - exact names, visibility, and signatures where directly observable
+2. Trace call chains with these scope rules:
+   - same module or file: follow internal function and method calls recursively until the chain terminates, delegates externally, or reaches a leaf
+   - external dependencies through imports or equivalent declarations: record them as integration points with public interface or contract details only
+3. Enumerate all entry points discovered in the traced scope that receive input from outside the module or file
+4. Mark each entry point as `change-relevant` or `non-relevant` based on requirement scope, affected files, and user-visible behavior
+5. For each `change-relevant` entry point, trace the data transformation pipeline step by step:
+   - record how the input changes at each step
+   - record intermediate representations or formats when they differ from the final output
+   - record external lookups that modify values, including configuration, constants, mapping tables, and reference data
+6. For each `non-relevant` entry point, record at minimum:
+   - entry point name and file:line
+   - input shape
+   - output shape
+7. If additional entry points share the same output path or transformation logic as a `change-relevant` entry point, reclassify them as `change-relevant` and trace them step by step
+8. Search for patterns related to:
    - data access: repository usage, ORM calls, query builders, raw SQL, migration references
    - external service calls: HTTP clients, SDK clients, queue producers or consumers, webhook handlers
    - validation logic: validator functions, schema parsers, assertions, guard clauses, constraint checks
    - user-visible state handling: state stores, reducers, hooks, loading or error states, view-model shaping
-4. Record each discovered element with exact file path and line number
+9. Record each discovered element with exact file path and line number
 
 ### Step 3: Data Model Discovery
 
@@ -149,6 +164,31 @@ Return the JSON result as the final response.
     ],
     "migrationFiles": ["path/to/migration"]
   },
+  "dataTransformationPipelines": [
+    {
+      "entryPoint": "functionOrMethodName (path/to/file:line)",
+      "steps": [
+        {
+          "order": 1,
+          "method": "functionOrMethodName (path/to/file:line)",
+          "input": "Input data or format at this step",
+          "output": "Output data or format at this step",
+          "externalLookups": ["Config.KEY lookup", "Reference table mapping"],
+          "transformation": "What changed and why it matters"
+        }
+      ],
+      "intermediateFormats": ["Intermediate representation if applicable"],
+      "finalOutput": "Final output shape or observable value"
+    }
+  ],
+  "entryPointInventory": [
+    {
+      "entryPoint": "functionOrMethodName (path/to/file:line)",
+      "classification": "change-relevant|non-relevant",
+      "inputShape": "Input type or shape",
+      "outputShape": "Output type or shape"
+    }
+  ],
   "constraints": [
     {
       "type": "validation|business_rule|configuration|assumption",
@@ -176,11 +216,18 @@ Return the JSON result as the final response.
 ## Completion Criteria
 
 - [ ] Parsed requirement context and identified analysis categories
-- [ ] Read affected files and traced direct dependencies
-- [ ] Recorded key interfaces and implementation elements with file:line evidence
+- [ ] Read affected files in full and recorded public and private implementation elements with file:line evidence, or documented scope limits in `limitations`
+- [ ] Traced call chains according to the scope rules, or documented incomplete traces in `limitations`
+- [ ] Enumerated all entry points in the traced scope and marked each as `change-relevant` or `non-relevant`
+- [ ] Traced data transformation pipelines step by step for all `change-relevant` entry points that transform incoming data
+- [ ] Recorded at minimum entry point name, input shape, and output shape for all `non-relevant` entry points
+- [ ] Reclassified and traced entry points that share the same output path or transformation logic as a `change-relevant` entry point
+- [ ] Recorded external lookups that modify output values, including configuration, constants, and mapping data
 - [ ] Performed data model discovery when data access patterns were present
 - [ ] Extracted constraints and focus areas with concrete risks
 - [ ] Checked existing tests for coverage signals
+- [ ] Populated `dataTransformationPipelines` for all traced pipelines
+- [ ] Populated `entryPointInventory` for all discovered entry points in the traced scope
 - [ ] Returned valid JSON
 """
 

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

@@ -98,6 +98,7 @@ For DesignDoc, additionally verify:
 - [ ] 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
+- [ ] Output Comparison section present when the design changes existing observable behavior, an external contract, or a persisted data shape
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -116,6 +117,7 @@ For DesignDoc, additionally verify:
 - **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
+- **Output comparison check**: When the Design Doc changes existing observable behavior, an external contract, or a persisted data shape, verify that a concrete output comparison method is defined with identical input, expected output fields or format, and diff method. When upstream analysis includes `dataTransformationPipelines`, each listed step must be mapped to the comparison that verifies it; steps excluded because data passes through unchanged must include rationale. Missing mappings or rationale → `important` issue (category: `completeness`)
 - **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**:
@@ -258,6 +260,7 @@ 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
+- [ ] Output Comparison defined when the design changes existing observable behavior, an external contract, or a persisted data shape
 - [ ] Verification Strategy aligns with design type and implementation approach
 - [ ] Compliance with project rules
 - [ ] Technical feasibility and reasonableness of estimates

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/technical-designer.toml

@@ -90,7 +90,7 @@ Must be performed before Design Doc creation:
    - Record and distinguish between existing implementation locations and planned new locations
 
 2. **Existing Interface Investigation** (Only when changing existing features)
-   - List major public methods of target service (about 5 important ones if over 10)
+   - List every public method of the target service with full signatures
    - Identify call sites using content search with appropriate search patterns
 
 3. **Similar Functionality Search and Decision** (Pattern 5 prevention from ai-development-guide skill)
@@ -189,7 +189,9 @@ Must be performed when creating Design Doc:
    - 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
+   - When the design changes existing observable behavior, an external contract, or a persisted data shape, define a concrete `Output Comparison` method: identical input, expected output fields or format, diff method, and a mapping from each listed pipeline step to the comparison that verifies it
+   - When `Codebase Analysis` provides `dataTransformationPipelines`, use them to populate the `Output Comparison` section. Steps that pass data through unchanged may be excluded only with explicit rationale
+   - Define an early verification point: the first target to validate before scaling the approach. For changes to existing observable behavior, external contracts, or persisted data shapes, this must be an output comparison of at least one representative case
 
 ### Change Impact Map【Required】
 Must be included when creating Design Doc:
@@ -252,6 +254,7 @@ Confirm and document conflicts with existing systems at each integration point t
   - `dataModel` informs schema references, data contracts, and persistence design
   - `focusAreas` indicate areas requiring deeper design attention
   - `constraints` inform design constraints, assumptions, and risk handling
+  - `dataTransformationPipelines` informs the `Output Comparison` section in Verification Strategy
   - 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
@@ -352,6 +355,7 @@ Implementation sample creation checklist:
 - [ ] **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)
+- [ ] **Output Comparison defined** when changing existing observable behavior, an external contract, or a persisted data shape (comparison input, expected output fields, diff method, and transformation pipeline coverage)
 
 **Reverse-engineer mode only**:
 - [ ] Every architectural claim cites file:line evidence

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/README.md

@@ -337,6 +337,14 @@ your-project/
 
 ---
 
+## Works With
+
+If your requirements already live in Linear or an existing PRD, [linear-prism](https://github.com/shinpr/linear-prism) can decompose them into implementation-ready tasks by reading the codebase, making dependencies explicit, and preserving Design Doc boundaries.
+
+Those tasks can then be passed into `$recipe-design` to enter the design phase with clearer scope and better task visibility.
+
+---
+
 ## FAQ
 
 **Q: What models does this work with?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.4.3",
+  "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",