codex-workflows 0.4.3 → 0.4.4

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

@@ -241,6 +241,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/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,7 @@ 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.
 
 ## 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/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/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.4",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",