codex-workflows 0.2.1 → 0.2.3

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
@@ -116,7 +109,11 @@ Classify each hypothesis by the following levels:
 - Example: "The implementation is wrong" → Was design_gap considered?
 - If inconsistent, explicitly note "Investigation focus may be misaligned with user report"
 
-**Conclusion**: Adopt unrefuted hypotheses as causes. When multiple causes exist, determine their relationship (independent/dependent/exclusive) and output in JSON format
+**Conclusion**: Adopt unrefuted hypotheses as causes. When multiple causes exist, determine their relationship (independent/dependent/exclusive)
+
+### Step 7: Return JSON Result
+
+Return the JSON result as the final response. See Output Format for the schema.
 
 ## Confidence Determination Criteria
 
@@ -205,6 +202,7 @@ Classify each hypothesis by the following levels:
 - [ ] Verified consistency with user report
 - [ ] Determined verification level for each hypothesis
 - [ ] Adopted unrefuted hypotheses as causes and determined relationship when multiple
+- [ ] Final response is the JSON output
 
 ## Output Self-Check
 - [ ] Confidence levels reflect all discovered evidence, including official documentation

package/README.md

@@ -88,7 +88,7 @@ Problem → investigator → verifier (ACH + Devil's Advocate) → solver → Ac
 ### Reverse Engineering
 
 ```
-Existing code → scope-discoverer → prd-creator → code-verifier → document-reviewer → Design Docs
+Existing code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator → code-verifier → document-reviewer → Design Docs
 ```
 
 ---
@@ -246,7 +246,7 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 | `code-verifier` | Document-code consistency verification |
 | `security-reviewer` | Security compliance review after implementation |
 | `rule-advisor` | Skill selection via metacognitive analysis |
-| `scope-discoverer` | Codebase scope discovery for reverse docs |
+| `scope-discoverer` | Codebase scope discovery for reverse docs, including PRD unit grouping |
 
 ### Diagnosis Agents
 

package/package.json

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