codex-workflows 0.2.2 → 0.2.3

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

@@ -83,7 +83,21 @@ Register the following and execute:
 
 ### Step 1: Investigation (investigator)
 
-Spawn investigator agent: "Comprehensively collect information related to the following phenomenon. Phenomenon: [Problem reported by user]. Problem essence: [taskEssence]. Investigation focus: [investigationFocus]. Applicable rules: [selectedRules summary]."
+Spawn investigator agent with the following prompt:
+
+```text
+Comprehensively collect information related to the following phenomenon.
+
+Phenomenon: [Problem reported by user]
+Problem essence: [taskEssence]
+Investigation focus: [investigationFocus]
+Applicable rules: [selectedRules summary]
+
+For change failures, also include:
+- what changed
+- what broke
+- what both areas share
+```
 
 **Expected output**: Evidence matrix, comparison analysis results, causal tracking results, list of unexplored areas, investigation limitations
 
@@ -92,12 +106,14 @@ Spawn investigator agent: "Comprehensively collect information related to the fo
 Review investigation output:
 
 **Quality Check** (verify output contains the following):
-- [ ] comparisonAnalysis
-- [ ] causalChain for each hypothesis (reaching stop condition)
+- [ ] `comparisonAnalysis` is present and `normalImplementation` is non-null, or explicitly states that no working implementation was found
+- [ ] causalChain for each hypothesis reaches a stop condition
 - [ ] causeCategory for each hypothesis
+- [ ] `investigationSources` covers at least 3 distinct source types
+- [ ] each hypothesis has supporting evidence with a concrete source
 - [ ] Investigation covering investigationFocus items (when provided)
 
-**If quality insufficient**: MUST re-spawn investigator agent specifying missing items
+**If quality insufficient**: MUST re-spawn investigator agent specifying the missing items and include the previous investigation output for context
 ENFORCEMENT: Proceeding to verifier with incomplete investigation data produces unreliable conclusions.
 
 **design_gap Escalation**:

package/.agents/skills/recipe-reverse-engineer/SKILL.md

@@ -69,6 +69,7 @@ Spawn scope-discoverer agent: "Discover functional scope targets in the codebase
 - No units discovered -> ask user for hints
 - `$STEP_1_OUTPUT.prdUnits` exists
 - All `sourceUnits` across `prdUnits` (flattened, deduplicated) match the set of `discoveredUnits` IDs — no unit missing, no unit duplicated
+- Each discovered unit's `unitInventory` has at least one non-empty category. If all categories are empty, re-run discovery with focus on that unit
 
 **[STOP — BLOCKING]** If human review enabled: Present `$STEP_1_OUTPUT.prdUnits` with their source unit mapping to user for confirmation.
 **CANNOT proceed until user explicitly confirms.**
@@ -79,7 +80,7 @@ Spawn scope-discoverer agent: "Discover functional scope targets in the codebase
 
 #### Step 2: PRD Generation
 
-Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRD_UNIT_NAME. Description: $PRD_UNIT_DESCRIPTION. Related Files: $PRD_UNIT_COMBINED_RELATED_FILES. Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS. Source Units: $PRD_UNIT_SOURCE_UNITS. Skip independent scope discovery. Use provided scope data. Create final version PRD based on code investigation within specified scope."
+Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRD_UNIT_NAME. Description: $PRD_UNIT_DESCRIPTION. Related Files: $PRD_UNIT_COMBINED_RELATED_FILES. Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS. Source Units: $PRD_UNIT_SOURCE_UNITS. Use provided scope as an investigation starting point. If tracing entry points reveals directly connected files outside this scope, include them. Create final version PRD based on thorough code investigation."
 
 **Store output as**: `$STEP_2_OUTPUT` (PRD path)
 
@@ -87,12 +88,13 @@ Spawn prd-creator agent: "Create reverse-engineered PRD for the following featur
 
 **Prerequisite**: $STEP_2_OUTPUT (PRD path from Step 2)
 
-Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. code_paths: $PRD_UNIT_COMBINED_RELATED_FILES. verbose: false."
+Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. verbose: false."
 
 **Store output as**: `$STEP_3_OUTPUT`
 
 **Quality Gate**:
-- consistencyScore >= 70 -> proceed to review
+- consistencyScore >= 70 and verifiableClaimCount >= 20 -> proceed to review (guards against shallow verification passes with too few extracted claims)
+- consistencyScore >= 70 and verifiableClaimCount < 20 -> re-run verifier because investigation depth is insufficient
 - consistencyScore < 70 -> flag for detailed review
 
 #### Step 4: Review
@@ -151,6 +153,7 @@ Map PRD units to Design Doc generation targets by resolving each PRD unit's `sou
 - `technicalProfile.publicInterfaces` -> Public Interfaces
 - `dependencies` -> Dependencies
 - `relatedFiles` -> Scope boundary
+- `unitInventory` -> Unit Inventory
 
 **Store output as**: `$STEP_6_OUTPUT`
 
@@ -168,6 +171,11 @@ Map PRD units to Design Doc generation targets by resolving each PRD unit's `sou
     "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
     "dependencies": ["UNIT-003"],
     "scopeBoundary": ["src/auth/*"],
+    "unitInventory": {
+      "routes": [],
+      "testFiles": [],
+      "publicExports": []
+    },
     "mappingRationale": "Default 1:1 mapping from PRD unit because technical scope is cohesive"
   }
 ]
@@ -186,13 +194,13 @@ Map PRD units to Design Doc generation targets by resolving each PRD unit's `sou
 
 **Scope**: Document current architecture as-is. This is a documentation task, not a design improvement task.
 
-Spawn technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: create. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Primary Files: $UNIT_PRIMARY_MODULES. Public Interfaces: $UNIT_PUBLIC_INTERFACES. Dependencies: $UNIT_DEPENDENCIES. Parent PRD: $APPROVED_PRD_PATH. Document current architecture as-is."
+Spawn technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: reverse-engineer. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Primary Files: $UNIT_PRIMARY_MODULES. Public Interfaces: $UNIT_PUBLIC_INTERFACES. Dependencies: $UNIT_DEPENDENCIES. Unit Inventory: $UNIT_INVENTORY. Parent PRD: $APPROVED_PRD_PATH. Document current architecture as-is. Use Unit Inventory as the completeness baseline."
 
 **Store output as**: `$STEP_7_OUTPUT`
 
 #### Step 8: Code Verification
 
-Spawn code-verifier agent: "Verify consistency between Design Doc and code implementation. doc_type: design-doc. document_path: $STEP_7_OUTPUT. code_paths: $UNIT_PRIMARY_MODULES. verbose: false."
+Spawn code-verifier agent: "Verify consistency between Design Doc and code implementation. doc_type: design-doc. document_path: $STEP_7_OUTPUT. verbose: false."
 
 **Store output as**: `$STEP_8_OUTPUT`
 

package/.codex/agents/code-verifier.toml

@@ -52,13 +52,6 @@ Skill Status:
 This agent outputs **verification results and discrepancy findings only**.
 Document modification and solution proposals are out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Claim Extraction** - Extract verifiable claims from document
-2. **Multi-source Evidence Collection** - Gather evidence from code, tests, and config
-3. **Consistency Classification** - Classify each claim's implementation status
-4. **Coverage Assessment** - Identify undocumented code and unimplemented specifications
-
 ## Verification Framework
 
 ### Claim Categories
@@ -97,28 +90,38 @@ For each claim, classify as one of:
 
 ## Execution Steps
 
-### Step 1: Document Analysis
+### Step 1: Document Analysis — Section-by-Section Claim Extraction
 
-1. Read the target document
-2. Extract specific, testable claims
+1. Read the target document in full
+2. Process each section individually:
+   - Extract all statements that make verifiable claims about code behavior, data structures, file paths, API contracts, or system behavior
+   - Record `{ sectionName, claimCount, claims[] }`
+   - If a section contains factual statements but yields zero claims, record that explicitly for review
 3. Categorize each claim
 4. Note ambiguous claims that cannot be verified
+5. Minimum claim threshold: if `verifiableClaimCount < 20`, re-read under-covered sections and extract additional claims before continuing. Fewer than 20 claims usually indicates shallow extraction rather than a fully analyzed document.
 
 ### Step 2: Code Scope Identification
 
-1. Extract file paths mentioned in document
-2. Infer additional relevant paths from context
-3. Build verification target list
+1. If `code_paths` are provided, use them as a starting point, not a ceiling
+2. If `code_paths` are not provided, extract file paths from the document and expand scope by searching for referenced identifiers
+3. Infer additional relevant paths from context
+4. Build and record the final verification target list
 
 ### Step 3: Evidence Collection
 
 For each claim:
 
-1. **Primary Search**: Find direct implementation
+1. **Primary Search**: Find direct implementation with Read/Grep
 2. **Secondary Search**: Check test files for expected behavior
 3. **Tertiary Search**: Review config and type definitions
 
-Record source location and evidence strength for each finding.
+Evidence rules:
+- Record source location and evidence strength for each finding
+- Existence claims must be verified with Grep or file enumeration before reporting
+- Behavioral claims must be backed by reading the implementation, not by naming alone
+- Identifier claims must compare exact strings from code against the document
+- Single-source findings remain low confidence
 
 ### Step 4: Consistency Classification
 
@@ -130,11 +133,15 @@ For each claim with collected evidence:
    - medium: 2 sources agree
    - low: 1 source only
 
-### Step 5: Coverage Assessment
+### Step 5: Reverse Coverage Assessment — Code-to-Document Direction
+
+Perform this step with actual tool-backed enumeration, not memory:
 
-1. **Document Coverage**: What percentage of code is documented?
-2. **Implementation Coverage**: What percentage of specs are implemented?
-3. List undocumented features and unimplemented specs
+1. Enumerate routes/endpoints in scope and record whether each is documented
+2. Enumerate test files in scope and record whether their existence is documented
+3. Enumerate public exports/interfaces in primary source files and record whether each is documented
+4. Compile undocumented code items from the enumerations
+5. Compile unimplemented document items from earlier claim verification
 
 ### Step 6: Return JSON Result
 
@@ -151,9 +158,16 @@ Return the JSON result as the final response. See Output Format for the schema.
   "summary": {
     "docType": "prd|design-doc",
     "documentPath": "/path/to/document.md",
+    "verifiableClaimCount": 24,
+    "matchCount": 20,
     "consistencyScore": 85,
     "status": "consistent|mostly_consistent|needs_review|inconsistent"
   },
+  "claimCoverage": {
+    "sectionsAnalyzed": 8,
+    "sectionsWithClaims": 7,
+    "sectionsWithZeroClaims": ["Appendix"]
+  },
   "discrepancies": [
     {
       "id": "D001",
@@ -162,9 +176,20 @@ Return the JSON result as the final response. See Output Format for the schema.
       "claim": "Brief claim description",
       "documentLocation": "PRD.md:45",
       "codeLocation": "src/auth.ts:120",
+      "evidence": "Observed implementation or enumeration result",
       "classification": "What was found"
     }
   ],
+  "reverseCoverage": {
+    "routesInCode": 6,
+    "routesDocumented": 5,
+    "undocumentedRoutes": ["POST /admin/reindex (src/routes/admin.ts:42)"],
+    "testFilesFound": 4,
+    "testFilesDocumented": 2,
+    "exportsInCode": 12,
+    "exportsDocumented": 10,
+    "undocumentedExports": ["rebuildSearchIndex (src/search/index.ts:18)"]
+  },
   "coverage": {
     "documented": ["Feature areas with documentation"],
     "undocumented": ["Code features lacking documentation"],
@@ -190,6 +215,8 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
                    - (minorDiscrepancies * 2)
 ```
 
+If `verifiableClaimCount < 20`, treat the score as unstable and return to Step 1 before finalizing. This threshold exists to prevent shallow extraction from producing an artificially high score.
+
 | Score | Status | Interpretation |
 |-------|--------|----------------|
 | 85-100 | consistent | Document accurately reflects code |
@@ -199,9 +226,11 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 
 ## Completion Criteria
 
-- [ ] Extracted all verifiable claims from document
+- [ ] Extracted claims section-by-section with per-section counts recorded
+- [ ] `verifiableClaimCount >= 20`
 - [ ] Collected evidence from multiple sources for each claim
 - [ ] Classified each claim (match/drift/gap/conflict)
+- [ ] Performed reverse coverage with route, test file, and public export enumeration
 - [ ] Identified undocumented features in code
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
@@ -209,9 +238,13 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 
 ## Output Self-Check
 - [ ] All findings are based on verification evidence (no modifications proposed)
+- [ ] Existence claims are backed by Grep or enumeration evidence
+- [ ] Behavioral claims are backed by reading the actual implementation
+- [ ] Identifier comparisons use exact strings from code
 - [ ] Each classification cites multiple sources (not single-source)
 - [ ] Low-confidence classifications are explicitly noted
 - [ ] Contradicting evidence is documented, not ignored
+- [ ] `reverseCoverage` includes concrete counts from tool-backed enumeration
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/investigator.toml

@@ -47,14 +47,6 @@ Skill Status:
 This agent outputs **evidence matrix and factual observations only**.
 Solution derivation is out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Multi-source information collection (Triangulation)** - Collect data from multiple sources without depending on a single source
-2. **External information collection (web search)** - Search official documentation, community, and known library issues
-3. **Hypothesis enumeration and causal tracking** - List multiple causal relationship candidates and trace to root cause
-4. **Impact scope identification** - Identify locations implemented with the same pattern
-5. **Unexplored areas disclosure** - Honestly report areas that could not be investigated
-
 ## Execution Steps
 
 ### Step 1: Problem Understanding and Investigation Strategy
@@ -70,9 +62,18 @@ Solution derivation is out of scope for this agent.
 
 ### Step 2: Information Collection
 
-- **Internal sources**: Code, git history, dependencies, configuration, Design Doc/ADR
-- **External sources (web search)**: Official documentation, Stack Overflow, GitHub Issues, package issue trackers
-- **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values)
+Investigate each source type below and record findings even when empty:
+
+| Source | Minimum Investigation Action |
+|--------|------------------------------|
+| Code | Read directly related files and search for the reported symbols, errors, or messages |
+| git history | Review recent history for affected files and compare working/broken states when applicable |
+| Dependencies | Inspect package manifests and relevant package versions or changelogs |
+| Configuration | Read relevant config files and search for related keys across the project |
+| Design Doc or ADR | Search for matching docs and read them. Record findings or explicitly record that none were found |
+| External | Search official documentation for the primary technology and for the reported error text. Record findings or explicitly record that no relevant result was found |
+
+**Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values)
 
 Information source priority:
 1. Comparison with "working implementation" in project
@@ -86,9 +87,7 @@ Information source priority:
 - Collect supporting and contradicting evidence for each hypothesis
 - Determine causeCategory: typo / logic_error / missing_constraint / design_gap / external_factor
 
-**Signs of shallow tracking**:
-- Stopping at "~ is not configured" → without tracing why it's not configured
-- Stopping at technical element names → without tracing why that state occurred
+**Tracking depth check**: Each causal chain must reach a stop condition. If it ends at a configuration state or technical label, continue tracing why that state exists.
 
 ### Step 4: Impact Scope Identification
 
@@ -172,7 +171,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 
 - [ ] Determined problem type and executed diff analysis for change failures
 - [ ] Output comparisonAnalysis
-- [ ] Investigated internal and external sources
+- [ ] Investigated each source type or recorded that it had no relevant findings
 - [ ] Enumerated 2+ hypotheses with causal tracking, evidence collection, and causeCategory determination for each
 - [ ] Determined impactScope and recurrenceRisk
 - [ ] Documented unexplored areas and investigation limitations

package/.codex/agents/prd-creator.toml

@@ -106,7 +106,7 @@ Output in the following structured format:
 ### For Final Version
 Storage location and naming convention follow the principles in documentation-criteria skill.
 
-**Handling Undetermined Items**: When information is insufficient, do not speculate. Instead, list questions in an "Undetermined Items" section.
+**Handling Undetermined Items**: When a claim cannot be confirmed directly from code, tests, or configuration, list the unresolved question in an "Undetermined Items" section.
 
 ## Output Policy
 Execute file output immediately. Final approval is managed by the orchestrator recipe.
@@ -116,10 +116,9 @@ Execute file output immediately. Final approval is managed by the orchestrator r
 - Understand and describe intent of each section
 - Limit questions to 3-5 in interactive mode
 
-## PRD Boundaries: Do Not Include Implementation Phases
+## PRD Boundaries
 
 **ENFORCEMENT**: PRDs MUST focus solely on "what to build" — implementation phases and task decomposition are out of scope.
-These are outside the scope of this document. PRDs MUST focus solely on "what to build."
 
 ## PRD Creation Best Practices
 
@@ -183,58 +182,74 @@ Mode for extracting specifications from existing implementation to create PRD. U
 ### External Scope Handling
 
 When `External Scope Provided: true` is specified:
-- Skip independent scope discovery (Step 1)
-- Use provided scope data: Feature, Description, Related Files, Entry Points
-- Focus investigation within the provided scope boundaries
+- Use provided scope data as an investigation starting point: Feature, Description, Related Files, Entry Points
+- If entry point tracing reveals directly connected files or routes outside the provided scope, include them and report that expansion
 
 When external scope is NOT provided:
 - Execute full scope discovery independently
 
 ### Reverse PRD Execution Policy
 **Create high-quality PRD through thorough investigation**
-- Investigate until code implementation is fully understood
-- Comprehensively confirm related files, tests, and configurations
-- Write specifications with confidence (minimize speculation and assumptions)
 
 **Language Standard**: Code is the single source of truth. Describe observable behavior in definitive form. When uncertain about a behavior, investigate the code further to confirm — move the claim to "Undetermined Items" only when the behavior genuinely cannot be determined from code alone (e.g., business intent behind a design choice).
 
+**Literal Transcription Rule**: Identifiers, URLs, parameter names, field names, component names, and string literals MUST be copied exactly as written in code. If code contains a typo, document the actual identifier and note the typo separately when needed.
+
 ### Confidence Gating
 
 Before documenting any claim, assess confidence level:
 
 | Confidence | Evidence | Output Format |
 |------------|----------|---------------|
-| Verified | Direct code observation, test confirmation | State as fact |
+| Verified | Direct code observation via Read/Grep, test confirmation | State as fact |
 | Inferred | Indirect evidence, pattern matching | Mark with context |
 | Unverified | No direct evidence, speculation | Add to "Undetermined Items" section |
 
 **Rules**:
-- Never document Unverified claims as facts
+- Unverified claims go to "Undetermined Items" only
 - Inferred claims require explicit rationale
 - Prioritize Verified claims in core requirements
 - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous
 
-### Reverse PRD Process
-1. **Investigation Phase** (skip if External Scope Provided)
-   - Analyze all files of target feature
-   - Understand expected behavior from test cases
-   - Collect related documentation and comments
-   - Fully grasp data flow and processing logic
+### Reverse PRD Investigation Protocol
+1. **Route and Entry Point Enumeration**
+   - Enumerate routes, endpoints, commands, or other entry points in the feature area
+   - Record each with exact method/path/name and handler as written in code
+
+2. **Entry Point Tracing**
+   - Read each handler or entry point implementation
+   - Trace invoked services, helpers, and downstream calls by reading their implementations
+   - Record actual behavior, parameters, and key branching
+
+3. **Data Model Investigation**
+   - Read schemas, types, migrations, or constants referenced by the traced flow
+   - Record field names, types, nullability, validation rules, and enum values exactly as written
+
+4. **Test File Discovery**
+   - Enumerate test files matching the feature area
+   - Read each discovered test and record tested behaviors
+   - If no tests are found for a traced handler or service, record that explicitly
+
+5. **Role and Permission Discovery**
+   - Search for middleware, guards, and role checks tied to the feature
+   - Record all observed roles and permissions
 
-2. **Specification Documentation**
-   - Apply Confidence Gating to each claim
-   - Accurately document specifications extracted from current implementation
-   - Only describe specifications clearly readable from code
+6. **Specification Documentation**
+   - Apply Confidence Gating to every claim
+   - Describe only behavior readable from code and tests
+   - Base core sections on the entry point list, traced flow, data model, and discovered tests
 
-3. **Minimal Confirmation Items**
-   - Only ask about truly undecidable important matters (maximum 3)
-   - Only parts related to business decisions, not implementation details
+7. **Minimal Confirmation Items**
+   - Ask only truly undecidable business questions
+   - Limit to 3 items maximum
 
 ### Quality Standards
 - Verified content: 80%+ of core requirements
 - Inferred content: 15% maximum with rationale
 - Unverified content: Listed in "Undetermined Items" only
 - Specification document with implementable specificity
+- All discovered entry points are accounted for in the PRD
+- Data model details match the code-level source of truth
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/scope-discoverer.toml

@@ -52,33 +52,15 @@ Skill Status:
 This agent outputs **scope discovery results, evidence, and PRD unit grouping**.
 Document generation (PRD content, Design Doc content) is out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Multi-source Discovery** - Collect evidence from routing, tests, directory structure, docs, modules, interfaces
-2. **Boundary Identification** - Identify logical boundaries between functional units
-3. **Relationship Mapping** - Map dependencies and relationships between discovered units
-4. **Confidence Assessment** - Assess confidence level with triangulation strength
-
-## Discovery Approach
-
-### When reference_architecture is provided (Top-Down)
-
-1. Apply RA layer definitions as initial classification framework
-2. Map code directories to RA layers
-3. Discover units within each layer
-4. Validate boundaries against RA expectations
-
-### When reference_architecture is none (Bottom-Up)
-
-1. Scan all discovery sources
-2. Identify natural boundaries from code structure
-3. Group related components into units
-4. Validate through cross-source confirmation
-
 ## Unified Scope Discovery
 
 Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units.
 
+When `reference_architecture` is provided:
+- Use its layer definitions to classify discovered code into layers
+- Validate unit boundaries against those expectations
+- Record deviations in `uncertainAreas`
+
 ### Discovery Sources
 
 | Source | Priority | Perspective | What to Look For |
@@ -121,23 +103,31 @@ Explore the codebase from both user-value and technical perspectives simultaneou
    - Also assign normalized grouping keys in `valueProfile.groupingKey` for persona, goal, and category; use short stable slugs (`kebab-case`) rather than free-form prose
    - Apply Granularity Criteria (see below)
 
-5. **Boundary Validation**
+5. **Unit Inventory Enumeration**
+   - For each discovered unit, enumerate:
+     - Routes or entry points in the unit's related files
+     - Test files covering the unit
+     - Public exports or interfaces in primary modules
+   - Store the results as `unitInventory`
+   - Use actual enumeration, not inferred summaries
+
+6. **Boundary Validation**
    - Verify each unit delivers distinct user value
    - Check for minimal overlap between units
    - Identify shared dependencies and cross-cutting concerns
 
-6. **Saturation Check**
+7. **Saturation Check**
    - Stop discovery when 3 consecutive new sources yield no new units
    - Mark discovery as saturated in output
 
-7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete)
+8. **PRD Unit Grouping** (execute only after steps 1-7 are fully complete)
    - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units
    - Grouping logic: units with the same `groupingKey.valueCategory` AND the same `groupingKey.userGoal` AND the same `groupingKey.targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units
    - Free-text fields (`targetPersona`, `userGoal`, `valueCategory`) are explanatory only and MUST NOT be used as grouping keys
    - Every discovered unit must appear in exactly one PRD unit's `sourceUnits`
    - Output as `prdUnits` alongside `discoveredUnits` (see Output Format)
 
-8. **Return JSON Result**
+9. **Return JSON Result**
    - Return the JSON result as the final response. See Output Format for the schema.
 
 ## Granularity Criteria
@@ -203,6 +193,11 @@ Note: These signals are informational only during steps 1-6. Keep all discovered
         "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
         "dataFlowSummary": "Request → Controller → Service → Repository → DB",
         "infrastructureDeps": ["database", "redis-cache"]
+      },
+      "unitInventory": {
+        "routes": ["POST /login -> AuthController.handleLogin (src/auth/controller.ts:24)"],
+        "testFiles": ["src/auth/service.test.ts"],
+        "publicExports": ["AuthService (src/auth/service.ts:10)"]
       }
     }
   ],
@@ -246,6 +241,7 @@ Note: These signals are informational only during steps 1-6. Keep all discovered
 - [ ] Reviewed test structure for feature organization
 - [ ] Detected module/service boundaries
 - [ ] Mapped public interfaces
+- [ ] Enumerated per-unit inventory for routes, test files, and public exports
 - [ ] Analyzed dependency graph
 - [ ] Applied granularity criteria (split/merge as needed)
 - [ ] Identified value profile (persona, goal, category) for each unit

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

@@ -89,28 +89,24 @@ Must be performed before Design Doc creation:
    - Clearly document similar component search results (found components or "none")
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
-### Integration Point Analysis【Important】
-Clarify integration points with existing components when adding new features or modifying existing ones:
-
-1. **Identify and Document Integration Points**
-   ```yaml
-   ## Integration Point Map
-   Integration Point 1:
-     Existing Component: [Component Name/Hook Name]
-     Integration Method: [Props passing/Context sharing/Custom Hook usage/etc]
-     Impact Level: High (Data Flow Change) / Medium (Props Usage) / Low (Read-Only)
-     Required Test Coverage: [Continuity Verification of Existing Components]
-   ```
-
-2. **Classification by Impact Level**
-   - **High**: Modifying or extending existing data flow or state management
-   - **Medium**: Using or updating existing component state/context
-   - **Low**: Read-only operations, rendering additions, etc.
-
-3. **Reflection in Design Doc**
-   - Create "## Integration Point Map" section
-   - Clarify responsibilities and boundaries at each integration point
-   - Define error behavior and loading states at design phase
+### Integration Points【Important】
+Document all integration points with existing components in a "## Integration Point Map" section.
+
+For each integration point, record:
+- Existing component or hook
+- Integration method
+- Impact level
+- Required test coverage
+
+Impact level criteria:
+- High: modifies or extends existing state flow or interaction flow
+- Medium: reuses or updates existing props, context, or API contracts
+- Low: read-only rendering, observation, or non-invasive composition
+
+For each integration boundary, define:
+- Input props or consumed context
+- Output events or effects
+- On Error behavior
 
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:
@@ -173,32 +169,13 @@ Perform before Design Doc creation:
 
 Common ADR needed when: Technical decisions common to multiple components
 
-### Integration Point Specification
-Document integration points with existing components (location, old Props, new Props, switching method).
-
 ### Data Contracts
 Define Props types and state management contracts between components (types, preconditions, guarantees, error behavior).
 
 ### State Transitions (When Applicable)
 Document state definitions and transitions for stateful components (loading, error, success states).
 
-### Integration Boundary Contracts【Required】
-Define Props types, event handlers, and error handling at component boundaries.
-
-```yaml
-Boundary Name: [Component Integration Point]
-  Input (Props): [Props type definition]
-  Output (Events): [Event handler signatures]
-  On Error: [How to handle errors (Error Boundary, error state, etc.)]
-```
-
-**Integration Boundaries:**
-- React → DOM: Component rendering to browser DOM
-- Build Tool → Browser: Build output to static files served by browser
-- API → Frontend: External API responses handled by frontend
-- Context → Component: Context values consumed by components
-
-Confirm and document conflicts with existing components (naming conventions, Props patterns, etc.) to prevent integration inconsistencies.
+Confirm and document conflicts with existing components at each integration point to prevent inconsistencies.
 
 ## UI Spec Integration
 
@@ -215,6 +192,7 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 - **Operation Mode**:
   - `create`: New creation (default)
   - `update`: Update existing document
+  - `reverse-engineer`: Document existing frontend architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
 - **PRD**: PRD document (if exists)
@@ -234,41 +212,15 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
   - Reason for changes
   - Sections needing updates
 
-## Document Output Format
-
-### ADR Creation (Multiple Option Comparison Mode)
-
-**Basic Structure**:
-```markdown
-# ADR-XXXX: [Title]
-Status: Proposed
-
-## Background
-[Frontend technical challenges and constraints in 1-2 sentences]
+- **Reverse-Engineer Context** (reverse-engineer mode only):
+  - Primary Files
+  - Public Interfaces
+  - Dependencies
+  - Unit Inventory (routes, test files, public exports)
 
-## Options
-### Option A: [Approach Name]
-- Overview: [Explain in one sentence]
-- Benefits: [2-3 items]
-- Drawbacks: [2-3 items]
-- Effort: X days
-
-### Option B/C: [Document similarly]
-
-## Comparison
-| Evaluation Axis | Option A | Option B | Option C |
-|-----------------|----------|----------|----------|
-| Implementation Effort | 3 days | 5 days | 2 days |
-| Maintainability | High | Medium | Low |
-| Performance Impact | Low | High | Medium |
-
-## Decision
-Option [X] selected. Reason: [2-3 sentences including trade-offs]
-```
-
-See ADR template in documentation-criteria skill for details.
+## Document Output Format
 
-### Normal Document Creation
+### Document Creation
 - **ADR**: `docs/adr/ADR-[4-digit number]-[title].md` (e.g., ADR-0001)
 - **Design Doc**: `docs/design/[feature-name]-design.md`
 - Follow respective templates (see documentation-criteria skill: design-template.md, adr-template.md, ui-spec-template.md)
@@ -376,21 +328,30 @@ function useUserData(userId: string) {
 - [ ] Comparison matrix completeness (including performance impact)
 
 ### Design Doc Checklist
+**All modes**:
+- [ ] **Code inspection evidence recorded** (required)
+- [ ] **Integration points enumerated with contracts** (required)
+- [ ] **Props and state contracts clarified** (required)
+- [ ] Component hierarchy and data flow clearly expressed in diagrams
+
+**Create/update mode only**:
 - [ ] **Agreement checklist completed** (most important)
 - [ ] **Prerequisite common ADRs referenced** (required)
 - [ ] **Change impact map created** (required)
-- [ ] **Integration boundary contracts defined** (required)
-- [ ] **Integration points completely enumerated** (required)
-- [ ] **Props type contracts clarified** (required)
 - [ ] **Component verification procedures for each phase** (required)
 - [ ] Response to requirements and design validity
 - [ ] Test strategy (React Testing Library) and error handling (Error Boundary)
-- [ ] Component hierarchy and data flow clearly expressed in diagrams
 - [ ] Props change matrix completeness
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest React best practices researched and references cited
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
 
+**Reverse-engineer mode only**:
+- [ ] Every architectural claim cites file:line evidence
+- [ ] Identifiers are transcribed exactly from code
+- [ ] Test existence is confirmed by enumeration
+- [ ] All provided Unit Inventory items are accounted for
+
 ## Acceptance Criteria Creation Guidelines
 
 **Principle**: Set specific, verifiable conditions in browser environment. Avoid ambiguous expressions, document in format convertible to React Testing Library test cases.
@@ -419,49 +380,41 @@ function useUserData(userId: string) {
 
 **Principle**: AC = User-observable behavior in browser verifiable in isolated CI environment
 
-## Latest Information Research Guidelines
-
-### Research Timing
-1. **Mandatory Research**:
-   - When considering new React library/UI framework introduction
-   - When designing performance optimization (code splitting, lazy loading)
-   - When designing accessibility implementation (WCAG compliance)
-   - When React major version upgrades (e.g., React 18 → 19)
-
-2. **Recommended Research**:
-   - Before implementing complex custom hooks
-   - When considering improvements to existing component patterns
+## Latest Information Research
 
-### Research Method
+Use current-year queries and cite sources in a `## References` section for create/update mode.
 
-**Required Research Timing**: New library introduction, performance optimization, accessibility design, React version upgrades
-
-**Specific Search Pattern Examples**:
-- `React new features best practices 2025` (new feature research)
-- `Zustand vs Redux Toolkit comparison 2025` (state management selection)
-- `React Server Components patterns` (design patterns)
-- `React breaking changes migration guide` (version upgrade)
-- `Tailwind CSS accessibility best practices` (accessibility research)
-- `[library name] official documentation` (official information)
-
-**Citation**: Add "## References" section at end of ADR/Design Doc with URLs and descriptions
-
-### Citation Format
-
-Add at the end of ADR/Design Doc in the following format:
-
-```markdown
-## References
-
-- [Title](URL) - Brief description of referenced content
-- [React Official Documentation](URL) - Related design principles and features
-- [Frontend Blog Article](URL) - Implementation patterns and best practices
-```
+Reverse-engineer mode skips latest-information research because it documents the existing frontend.
 
 ## Update Mode Operation
 - **ADR**: Update existing file for minor changes, create new file for major changes
 - **Design Doc**: Add revision section and record change history
 
+## Reverse-Engineer Mode (As-Is Documentation)
+
+Use this mode when documenting existing frontend architecture rather than proposing changes.
+
+What to skip:
+- ADR creation
+- Option comparison
+- Change Impact Map
+- Implementation Approach Decision
+- Latest Information Research
+
+Execution steps:
+1. Enumerate public components, hooks, routes, and other entry points from Primary Files and Unit Inventory. Record each with file:line evidence
+2. Trace actual props flow, state flow, context usage, and API interaction paths through directly connected code. Record observed behavior with file:line evidence
+3. Record contracts exactly as implemented:
+   - props and consumed context
+   - emitted events and side effects
+   - rendered states, loading states, and error states
+4. Read types, defaults, variants, constants, and enums referenced by the traced flow. Record names and values exactly as written in code
+5. Enumerate tests for the unit and map each test file to the components, hooks, or flows it covers. Record uncovered Unit Inventory items explicitly
+
+Completion rule for reverse-engineer mode:
+- Every Unit Inventory route or public export is accounted for in the Design Doc
+- Every claim about component structure, props flow, state flow, API interaction, or error handling cites file:line evidence
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

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

@@ -123,28 +123,24 @@ When the design introduces or significantly modifies data structures:
    - 3+ criteria fail → New structure justified
    - Record decision and rationale in Design Doc
 
-### Integration Point Analysis【Important】
-Clarify integration points with existing systems when adding new features or modifying existing ones:
-
-1. **Identify and Document Integration Points**
-   ```yaml
-   ## Integration Point Map
-   Integration Point 1:
-     Existing Component: [Component/module name, function/method name]
-     Integration Method: [Hook Addition/Call Addition/Data Reference/etc]
-     Impact Level: High (Process Flow Change) / Medium (Data Usage) / Low (Read-Only)
-     Required Test Coverage: [Continuity Verification of Existing Features]
-   ```
-
-2. **Classification by Impact Level**
-   - **High**: Modifying or extending existing process flows
-   - **Medium**: Using or updating existing data
-   - **Low**: Read-only operations, log additions, etc.
-
-3. **Reflection in Design Doc**
-   - Create "## Integration Point Map" section
-   - Clarify responsibilities and boundaries at each integration point
-   - Define error behavior at design phase
+### Integration Points【Important】
+Document all integration points with existing systems in a "## Integration Point Map" section.
+
+For each integration point, record:
+- Existing component and method
+- Integration method
+- Impact level
+- Required test coverage
+
+Impact level criteria:
+- High: modifies or extends an existing process flow
+- Medium: reuses or updates existing data or contracts
+- Low: read-only interaction, observation, or non-invasive integration
+
+For each integration boundary, define:
+- Input
+- Output
+- On Error
 
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:
@@ -213,32 +209,20 @@ Perform before Design Doc creation:
 
 Common ADR needed when: Technical decisions common to multiple components
 
-### Integration Point Specification
-Document integration points with existing system (location, old implementation, new implementation, switching method).
-
 ### Data Contracts
 Define input/output between components (types, preconditions, guarantees, error behavior).
 
 ### State Transitions (When Applicable)
 Document state definitions and transitions for stateful components.
 
-### Integration Boundary Contracts【Required】
-Define input/output, sync/async, and error handling at component boundaries in language-agnostic manner.
-
-```yaml
-Boundary Name: [Connection Point]
-  Input: [What is received]
-  Output: [What is returned (specify sync/async)]
-  On Error: [How to handle]
-```
-
-Confirm and document conflicts with existing systems (priority, naming conventions, etc.) to prevent integration inconsistencies.
+Confirm and document conflicts with existing systems at each integration point to prevent inconsistencies.
 
 ## Required Information
 
 - **Operation Mode**:
   - `create`: New creation (default)
   - `update`: Update existing document
+  - `reverse-engineer`: Document existing architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
 - **PRD**: PRD document (if exists)
@@ -257,40 +241,15 @@ Confirm and document conflicts with existing systems (priority, naming conventio
   - Reason for changes
   - Sections needing updates
 
-## Document Output Format
-
-### ADR Creation (Multiple Option Comparison Mode)
+- **Reverse-Engineer Context** (reverse-engineer mode only):
+  - Primary Files
+  - Public Interfaces
+  - Dependencies
+  - Unit Inventory (routes, test files, public exports)
 
-**Basic Structure**:
-```markdown
-# ADR-XXXX: [Title]
-Status: Proposed
-
-## Background
-[Technical challenges and constraints in 1-2 sentences]
-
-## Options
-### Option A: [Approach Name]
-- Overview: [Explain in one sentence]
-- Benefits: [2-3 items]
-- Drawbacks: [2-3 items]
-- Effort: X days
-
-### Option B/C: [Document similarly]
-
-## Comparison
-| Evaluation Axis | Option A | Option B | Option C |
-|-----------------|----------|----------|----------|
-| Implementation Effort | 3 days | 5 days | 2 days |
-| Maintainability | High | Medium | Low |
-
-## Decision
-Option [X] selected. Reason: [2-3 sentences including trade-offs]
-```
-
-See ADR template in documentation-criteria skill for details.
+## Document Output Format
 
-### Normal Document Creation
+### Document Creation
 - **ADR**: `docs/adr/ADR-[4-digit number]-[title].md` (e.g., ADR-0001)
 - **Design Doc**: `docs/design/[feature-name]-design.md`
 - Follow respective templates (`template.md`)
@@ -344,25 +303,33 @@ Implementation sample creation checklist:
 - [ ] Comparison matrix completeness
 
 ### Design Doc Checklist
+**All modes**:
+- [ ] **Standards identification gate completed** (required)
+- [ ] **Code inspection evidence recorded** (required)
+- [ ] **Integration points enumerated with contracts** (required)
+- [ ] **Data contracts clarified** (required)
+- [ ] Architecture and data flow clearly expressed in diagrams
+
+**Create/update mode only**:
 - [ ] **Agreement checklist completed** (most important)
 - [ ] **Prerequisite common ADRs referenced** (required)
 - [ ] **Change impact map created** (required)
-- [ ] **Integration boundary contracts defined** (required)
-- [ ] **Integration points completely enumerated** (required)
-- [ ] **Data contracts clarified** (required)
 - [ ] **E2E verification procedures for each phase** (required)
 - [ ] Response to requirements and design validity
 - [ ] Test strategy and error handling
-- [ ] Architecture and data flow clearly expressed in diagrams
 - [ ] Interface change matrix completeness
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest best practices researched and references cited
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
-- [ ] **Standards identification gate completed** (required)
-- [ ] **Code inspection evidence recorded** (required)
 - [ ] **Data representation decision documented** (when new structures introduced)
 - [ ] **Field propagation map included** (when fields cross boundaries)
 
+**Reverse-engineer mode only**:
+- [ ] Every architectural claim cites file:line evidence
+- [ ] Identifiers are transcribed exactly from code
+- [ ] Test existence is confirmed by enumeration
+- [ ] All provided Unit Inventory items are accounted for
+
 
 ## Acceptance Criteria Creation Guidelines
 
@@ -397,53 +364,42 @@ Implementation sample creation checklist:
 
 *Note: Non-functional requirements (performance, reliability, etc.) are defined in the "Non-functional Requirements" section and automatically verified by quality check tools
 
-## Latest Information Research Guidelines
-
-### Research Timing
-1. **Mandatory Research**:
-   - When considering new technology/library introduction
-   - When designing performance optimization
-   - When designing security-related implementation
-   - When major version upgrades of existing technology
-
-2. **Recommended Research**:
-   - Before implementing complex algorithms
-   - When considering improvements to existing patterns
+## Latest Information Research
 
-### Research Method
+Use current-year queries and cite sources in a `## References` section for create/update mode.
 
-**Required Research Timing**: New technology introduction, performance optimization, security design, major version upgrades
-
-**Specific Search Pattern Examples**:
-To get latest information, always check current year before searching:
-```bash
-date +%Y  # e.g., 2025
-```
-Include this year in search queries:
-- `[technology] [feature] best practices {current_year}` (new feature research)
-- `[tech A] vs [tech B] performance comparison {current_year}` (technology selection)
-- `[architecture pattern] [concern] patterns` (design patterns)
-- `[framework] v[X] breaking changes migration guide` (version upgrade)
-- `[framework name] official documentation` (official docs don't need year)
-
-**Citation**: Add "## References" section at end of ADR/Design Doc with URLs and descriptions
-
-### Citation Format
-
-Add at the end of ADR/Design Doc in the following format:
-
-```markdown
-## References
-
-- [Title](URL) - Brief description of referenced content
-- [Framework Official Documentation](URL) - Related design principles and features
-- [Technical Blog Article](URL) - Implementation patterns and best practices
-```
+Reverse-engineer mode skips latest-information research because it documents what exists.
 
 ## Update Mode Operation
 - **ADR**: Update existing file for minor changes, create new file for major changes
 - **Design Doc**: Add revision section and record change history
 
+## Reverse-Engineer Mode (As-Is Documentation)
+
+Use this mode when documenting existing architecture rather than proposing changes.
+
+What to skip:
+- ADR creation
+- Option comparison
+- Change Impact Map
+- Field Propagation Map
+- Implementation Approach Decision
+- Latest Information Research
+
+Execution steps:
+1. Enumerate entry points from Primary Files and Unit Inventory. Record each public handler, command, or exported interface with file:line evidence
+2. Trace each entry point through directly called services, helpers, and data-access code. Record actual data flow and error handling with file:line evidence
+3. Record contracts exactly as implemented:
+   - inputs and parameters
+   - outputs and response shapes
+   - middleware, guards, and integration boundaries
+4. Read schemas, types, defaults, constants, and enums referenced by the traced flow. Record names and values exactly as written in code
+5. Enumerate tests for the unit and map each test file to the interfaces or flows it covers. Record uncovered Unit Inventory items explicitly
+
+Completion rule for reverse-engineer mode:
+- Every Unit Inventory route or public export is accounted for in the Design Doc
+- Every claim about architecture, data flow, public contracts, integrations, or error handling cites file:line evidence
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

package/.codex/agents/verifier.toml

@@ -46,13 +46,6 @@ Skill Status:
 This agent outputs **investigation result verification and conclusion derivation only**.
 Solution derivation is out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Triangulation Supplementation** - Explore information sources not covered in the investigation to supplement results
-2. **ACH (Analysis of Competing Hypotheses)** - Generate alternative hypotheses beyond those listed in the investigation and evaluate consistency with evidence
-3. **Devil's Advocate** - Assume "the investigation results are wrong" and actively seek refutation
-4. **Conclusion Derivation** - Adopt unrefuted hypotheses as causes and determine relationship when multiple
-
 ## Execution Steps
 
 ### Step 1: Investigation Results Verification Preparation
@@ -71,11 +64,11 @@ Solution derivation is out of scope for this agent.
 - Verify logical validity of impactAnalysis (without additional searches)
 
 ### Step 2: Triangulation Supplementation
-Explore information sources not confirmed in the investigation:
-- Different code areas
-- Different configuration files
-- Related external documentation
-- Different perspectives from git history
+Identify which source types are missing from `investigationSources`, then investigate at least one uncovered source type.
+
+If all source types were already covered, investigate a different code area or configuration path than the original investigation.
+
+Record each supplementary finding and its impact on the existing hypotheses.
 
 ### Step 3: External Information Reinforcement (web search)
 - Official information about hypotheses found in investigation

package/package.json

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