codex-workflows 0.3.1 → 0.4.0

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

@@ -197,6 +197,22 @@ Invariants:
   - [Conditions that remain unchanged before and after processing]
 ```
 
+### Test Boundaries
+
+#### Mock Boundary Decisions
+
+| Dependency / Boundary | Test Level | Use Real Dependency | Isolation Method | Rationale |
+|-----------------------|------------|---------------------|------------------|-----------|
+| [Repository / API / queue / hook] | [integration / e2e] | [Yes / No] | [mock / fake / local test env / browser harness] | [Why this boundary should behave this way in tests] |
+
+#### Data Layer Verification Strategy
+
+- Data storage involved: [Yes / No]
+- Schema or model references: [table / collection / model names or N/A]
+- Real verification approach: [container DB / dedicated test DB / in-memory adapter / browser fixture / N/A]
+- Query and repository coverage: [How repository, ORM, or query paths will be verified]
+- Migration compatibility check: [How schema drift will be detected or why N/A]
+
 ### Field Propagation Map (When Fields Cross Boundaries)
 
 | Field | Boundary | Status | Detail |

package/.agents/skills/integration-e2e-testing/SKILL.md

@@ -60,10 +60,13 @@ Each test MUST include the following annotations:
 // Behavior: [Trigger] -> [Process] -> [Observable Result]
 // @category: core-functionality | integration | edge-case | e2e
 // @dependency: none | [component names] | full-system
+// @real-dependency: [component names] (optional)
 // @complexity: low | medium | high
 // ROI: [score]
 ```
 
+Adapt comment syntax to the project's language when generating or reviewing test skeletons.
+
 ### Verification Items (Optional)
 
 When verification points need explicit enumeration:
@@ -110,7 +113,7 @@ The test runner or framework in the project determines the appropriate file exte
 |-------|-------------------|
 | Behavior Verification | No assertion for "observable result" in skeleton |
 | Verification Item Coverage | Listed items not all covered by assertions |
-| Mock Boundary | Internal components mocked in integration test |
+| Mock Boundary | Real dependencies from `@real-dependency` are isolated away or internal components are mocked without rationale |
 
 ### Implementation Quality
 

package/.agents/skills/recipe-front-design/SKILL.md

@@ -17,8 +17,10 @@ description: "Execute from requirement analysis to frontend design document crea
 
 **Execution Method**:
 - Requirement analysis -> performed by requirement-analyzer
+- Codebase analysis -> performed by codebase-analyzer
 - UI Specification creation -> performed by ui-spec-designer
 - Design document creation -> performed by technical-designer-frontend
+- Design verification -> performed by code-verifier
 - Document review -> performed by document-reviewer
 
 Orchestrator spawns agents and passes structured data between them.
@@ -68,8 +70,10 @@ Then create the UI Specification:
 ### Step 3: Design Document Creation Phase
 Create appropriate design documents according to scale determination:
 - For ADR: Spawn technical-designer-frontend agent: "Create ADR for [technical decision]"
-- For Design Doc: Spawn technical-designer-frontend agent: "Create Design Doc based on requirements. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec."
-- Spawn document-reviewer agent: "Review [document path] for consistency and completeness"
+- For Design Doc: Spawn codebase-analyzer agent first: "Analyze the existing codebase to provide evidence for frontend Design Doc creation. Focus on existing implementations, state paths, API integrations, and constraints the design should respect. requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend affected files and directories from requirement-analyzer]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+- For Design Doc: Spawn technical-designer-frontend agent: "Create Design Doc based on requirements. Codebase Analysis: [JSON from codebase-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec."
+- Spawn code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]. verbose: false."
+- Spawn document-reviewer agent: "Review the Design Doc for consistency and completeness. doc_type: DesignDoc. target: [document path]. mode: composite. code_verification: [JSON from code-verifier]"
 
 **[STOP -- BLOCKING]** Present design alternatives and trade-offs, obtain user approval.
 **CANNOT proceed until user explicitly approves the design document.**
@@ -80,6 +84,7 @@ ENFORCEMENT: Every stop point MUST be respected. Skipping user approval invalida
 
 - [ ] Requirement analysis completed and approved
 - [ ] UI Specification created and approved
+- [ ] Codebase analysis completed before frontend Design Doc creation
 - [ ] Design document created and approved
 - [ ] All document reviews passed
 

package/.agents/skills/recipe-fullstack-implement/SKILL.md

@@ -90,6 +90,8 @@ When user responds to questions:
 - [ ] Identified current progress position
 - [ ] Clarified next step
 - [ ] Recognized stopping points
+- [ ] codebase-analyzer included before each Design Doc creation
+- [ ] code-verifier included before each Design Doc review
 - [ ] **Environment check**: Can I execute per-task commit cycle?
   - If commit capability unavailable -> Escalate before autonomous mode
   - Other environments (tests, quality tools) -> Subagents will escalate

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

@@ -128,6 +128,8 @@ After acceptance-test-generator execution, when spawning work-planner, communica
 - [ ] Requirement analysis completed and user-confirmed
 - [ ] Layer routing determined (backend / frontend / fullstack)
 - [ ] Correct workflow followed per layer routing
+- [ ] codebase-analyzer included before Design Doc creation for Medium/Large flows
+- [ ] code-verifier included before document-reviewer for Design Doc review
 - [ ] All stopping points honored with user confirmation obtained
 - [ ] Quality-fixer spawned before every commit
 - [ ] All tasks committed or escalation completed

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

@@ -101,7 +101,7 @@ Spawn code-verifier agent: "Verify consistency between PRD and code implementati
 
 **Required Input**: $STEP_3_OUTPUT (verification data from Step 3)
 
-Spawn document-reviewer agent: "Review the following PRD considering code verification findings. doc_type: PRD. target: $STEP_2_OUTPUT. mode: composite. Code Verification Results: $STEP_3_OUTPUT. Additional Review Focus: Alignment between PRD claims and verification evidence, resolution recommendations for each discrepancy, completeness of undocumented feature coverage."
+Spawn document-reviewer agent: "Review the following PRD considering code verification findings. doc_type: PRD. target: $STEP_2_OUTPUT. mode: composite. code_verification: $STEP_3_OUTPUT. Additional Review Focus: Alignment between PRD claims and verification evidence, resolution recommendations for each discrepancy, completeness of undocumented feature coverage."
 
 **Store output as**: `$STEP_4_OUTPUT`
 
@@ -208,7 +208,7 @@ Spawn code-verifier agent: "Verify consistency between Design Doc and code imple
 
 **Required Input**: $STEP_8_OUTPUT (verification data from Step 8)
 
-Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doc_type: DesignDoc. target: $STEP_7_OUTPUT. mode: composite. Code Verification Results: $STEP_8_OUTPUT. Parent PRD: $APPROVED_PRD_PATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions."
+Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doc_type: DesignDoc. target: $STEP_7_OUTPUT. mode: composite. code_verification: $STEP_8_OUTPUT. Parent PRD: $APPROVED_PRD_PATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions."
 
 **Store output as**: `$STEP_9_OUTPUT`
 

package/.agents/skills/recipe-update-doc/SKILL.md

@@ -32,8 +32,8 @@ ENFORCEMENT: Skipping document-reviewer risks propagating inconsistencies to dow
 Target document -> [Stop: Confirm changes]
                         |
               technical-designer / technical-designer-frontend / prd-creator (update mode)
-                        |
-              document-reviewer -> [Stop: Review approval]
+                        | (Design Doc only)
+              code-verifier -> document-reviewer -> [Stop: Review approval]
                         | (Design Doc only)
               design-sync -> [Stop: Final approval]
 ```
@@ -107,13 +107,23 @@ Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Docume
 
 ### Step 5: Document Review [Stop]
 
-**[STOP — BLOCKING]** Present review results to user for approval.
-**CANNOT proceed until user explicitly confirms.**
+For Design Doc updates, first verify the updated document against code:
+
+Spawn code-verifier agent: "Verify the updated Design Doc against current code. doc_type: design-doc. document_path: [path from Step 1]. verbose: false."
 
-Spawn document-reviewer agent: "Review the following updated document. doc_type: [Design Doc / PRD / ADR]. target: [path from Step 1]. mode: standard. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."
+**Store output as**: `$CODE_VERIFICATION_OUTPUT`
+
+For Design Doc updates:
+Spawn document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. target: [path from Step 1]. mode: composite. code_verification: $CODE_VERIFICATION_OUTPUT. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."
+
+For PRD or ADR updates:
+Spawn document-reviewer agent: "Review the following updated document. doc_type: [PRD or ADR]. target: [path from Step 1]. mode: composite. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."
 
 **Store output as**: `$STEP_5_OUTPUT`
 
+**[STOP — BLOCKING]** Present review results to user for approval.
+**CANNOT proceed until user explicitly confirms.**
+
 **On review result**:
 - Approved -> Proceed to Step 6
 - Needs revision -> Return to Step 4 with review feedback (max 2 iterations):
@@ -151,6 +161,7 @@ For Design Doc, spawn design-sync agent: "Verify consistency of the updated Desi
 - [ ] Identified target document
 - [ ] Clarified change content with user
 - [ ] Updated document via appropriate agent (update mode)
+- [ ] Ran code-verifier before document-reviewer for Design Doc updates
 - [ ] Spawned document-reviewer and addressed feedback
 - [ ] Spawned design-sync for consistency verification (Design Doc only)
 - [ ] Obtained user approval for updated document

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

@@ -65,13 +65,15 @@ The following subagents are available:
 
 ### Document Creation Agents
 6. **requirement-analyzer**: Requirement analysis and work scale determination
-7. **prd-creator**: Product Requirements Document creation
-8. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features)
-9. **technical-designer**: ADR/Design Doc creation
-10. **work-planner**: Work plan creation from Design Doc and test skeletons
-11. **document-reviewer**: Single document quality and rule compliance check
-12. **design-sync**: Design Doc consistency verification across multiple documents
-13. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs
+7. **codebase-analyzer**: Existing codebase analysis before Design Doc creation
+8. **prd-creator**: Product Requirements Document creation
+9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features)
+10. **technical-designer**: ADR/Design Doc creation
+11. **work-planner**: Work plan creation from Design Doc and test skeletons
+12. **document-reviewer**: Single document quality and rule compliance check
+13. **code-verifier**: Document-code consistency verification for review inputs
+14. **design-sync**: Design Doc consistency verification across multiple documents
+15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs
 
 ## Orchestration Principles
 
@@ -105,6 +107,9 @@ Spawn agents using natural language prompts. Provide clear context about what th
 **requirement-analyzer**:
 > "Analyze the following requirements and determine the work scale: [user requirements]. Perform requirement analysis and scale determination."
 
+**codebase-analyzer**:
+> "Analyze the existing codebase to provide evidence for Design Doc creation. Focus on existing implementations, data model elements, and constraints the design should respect. requirement_analysis: [JSON]. prd_path: [path if available]. requirements: [original user requirements]. layer: [target layer if applicable]. target_paths: [paths if narrowed]. Return codebase facts and focus areas."
+
 **task-executor**:
 > "Execute the implementation task defined in docs/plans/tasks/[filename].md. Complete the implementation following TDD Red-Green-Refactor."
 
@@ -175,9 +180,11 @@ All agents MUST use this vocabulary consistently:
 
 Subagents respond in JSON format. The final response from each JSON-returning subagent must be the JSON payload itself, with no trailing prose. Key fields for orchestrator decisions:
 - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions
+- **codebase-analyzer**: analysisScope, existingElements, dataModel, focusAreas, limitations
 - **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file/test_environment_not_ready), testsAdded, requiresTestReview
 - **quality-fixer**: status (approved/blocked). For blocked responses, discriminate by `reason`: specification conflicts use `blockingIssues[]`; execution prerequisites use `missingPrerequisites[]`, and each item provides its own `resolutionSteps`
 - **document-reviewer**: verdict.decision (approved/approved_with_conditions/needs_revision/rejected)
+- **code-verifier**: summary, discrepancies, reverseCoverage
 - **design-sync**: sync_status (CONFLICTS_FOUND/NO_CONFLICTS) — text format with [SUMMARY] block
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
 - **security-reviewer**: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes
@@ -212,7 +219,7 @@ Document generation agents (work-planner, technical-designer, prd-creator) can u
 
 When receiving new features or change requests, start with requirement-analyzer.
 
-### Large Scale (6+ Files) - 11 Steps (backend) / 13 Steps (frontend/fullstack)
+### Large Scale (6+ Files) - 13 Steps (backend) / 15 Steps (frontend/fullstack)
 
 1. requirement-analyzer: Requirement analysis + Check existing PRD **[Stop]**
 2. prd-creator: PRD creation
@@ -221,24 +228,35 @@ When receiving new features or change requests, start with requirement-analyzer.
 5. **(frontend/fullstack only)** document-reviewer: UI Spec review **[Stop: UI Spec Approval]**
 6. technical-designer: ADR creation (if architecture/technology/data flow changes)
 7. document-reviewer: ADR review (if ADR created) **[Stop: ADR Approval]**
-8. technical-designer: Design Doc creation
-9. document-reviewer: Design Doc review
-10. design-sync: Consistency verification **[Stop: Design Doc Approval]**
-11. acceptance-test-generator: Test skeleton generation, pass to work-planner
-12. work-planner: Work plan creation **[Stop: Batch approval]**
-13. task-decomposer: Autonomous execution to Completion report
+8. codebase-analyzer: Codebase analysis (pass requirement-analyzer output and PRD path when available)
+9. technical-designer: Design Doc creation
+10. code-verifier: Design Doc verification against code
+11. document-reviewer: Design Doc review with code verification evidence
+12. design-sync: Consistency verification **[Stop: Design Doc Approval]**
+13. acceptance-test-generator: Test skeleton generation, pass to work-planner
+14. work-planner: Work plan creation **[Stop: Batch approval]**
+15. task-decomposer: Autonomous execution to Completion report
 
-### Medium Scale (3-5 Files) - 7 Steps (backend) / 9 Steps (frontend/fullstack)
+### Medium Scale (3-5 Files) - 9 Steps (backend) / 11 Steps (frontend/fullstack)
 
 1. requirement-analyzer: Requirement analysis **[Stop]**
-2. **(frontend/fullstack only)** Ask user for prototype code; ui-spec-designer: UI Spec creation
-3. **(frontend/fullstack only)** document-reviewer: UI Spec review **[Stop: UI Spec Approval]**
-4. technical-designer: Design Doc creation
-5. document-reviewer: Design Doc review
-6. design-sync: Consistency verification **[Stop: Design Doc Approval]**
-7. acceptance-test-generator: Test skeleton generation, pass to work-planner
-8. work-planner: Work plan creation **[Stop: Batch approval]**
-9. task-decomposer: Autonomous execution to Completion report
+2. codebase-analyzer: Codebase analysis
+3. **(frontend/fullstack only)** Ask user for prototype code; ui-spec-designer: UI Spec creation
+4. **(frontend/fullstack only)** document-reviewer: UI Spec review **[Stop: UI Spec Approval]**
+5. technical-designer: Design Doc creation
+6. code-verifier: Design Doc verification against code
+7. document-reviewer: Design Doc review with code verification evidence
+8. design-sync: Consistency verification **[Stop: Design Doc Approval]**
+9. acceptance-test-generator: Test skeleton generation, pass to work-planner
+10. work-planner: Work plan creation **[Stop: Batch approval]**
+11. task-decomposer: Autonomous execution to Completion report
+
+### 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 Design Doc path to code-verifier
+- Pass code-verifier JSON to document-reviewer as `code_verification`
 
 ### Small Scale (1-2 Files) - 2 Steps
 

package/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md

@@ -10,7 +10,7 @@ This reference defines the orchestration flow for projects spanning multiple lay
 
 ## Design Phase
 
-### Large Scale Fullstack (6+ Files) - 12 Steps
+### Large Scale Fullstack (6+ Files) - 14 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
@@ -20,27 +20,35 @@ This reference defines the orchestration flow for projects spanning multiple lay
 | 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
 | 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec |
 | 6 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 7 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 8 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 9 | document-reviewer x2 | Review each Design Doc (one invocation per doc) | Reviews |
-| 10 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 11 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 12 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+| 7 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
+| 8 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 9 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
+| 10 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 11 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 13 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
 
-### Medium Scale Fullstack (3-5 Files) - 10 Steps
+### Medium Scale Fullstack (3-5 Files) - 12 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
 | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale |
-| 2 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
-| 3 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec |
-| 4 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 5 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 6 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 7 | document-reviewer x2 | Review each Design Doc (one invocation per doc) | Reviews |
-| 8 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 9 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 10 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+| 2 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
+| 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
+| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec |
+| 5 | document-reviewer | UI Spec review **[Stop]** | Approval |
+| 6 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 7 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
+| 8 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 9 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 10 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 11 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 12 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+
+### Parallelization in Multi-Agent Steps
+
+Steps marked `x2` run independently per layer and can execute in parallel when supported.
 
 ### Layer Context in Design Doc Creation
 
@@ -48,19 +56,35 @@ When spawning Design Doc creation for each layer, pass explicit context:
 
 **Large Scale (PRD available) -- Backend Design Doc**:
 **Agent**: Spawn technical-designer
-> "Create a backend Design Doc from PRD at [path]. Focus on: API contracts, data layer, business logic, service architecture."
+> "Create a backend Design Doc from PRD at [path]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
+
+**Large Scale (PRD available) -- Backend Codebase Analysis**:
+**Agent**: Spawn codebase-analyzer
+> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. prd_path: [path]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
 
 **Large Scale (PRD available) -- Frontend Design Doc**:
 **Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc from PRD at [path]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+> "Create a frontend Design Doc from PRD at [path]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+
+**Large Scale (PRD available) -- Frontend Codebase Analysis**:
+**Agent**: Spawn codebase-analyzer
+> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. prd_path: [path]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
 
 **Medium Scale (no PRD) -- Backend Design Doc**:
 **Agent**: Spawn technical-designer
-> "Create a backend Design Doc based on the following requirements: [requirement-analyzer output]. Focus on: API contracts, data layer, business logic, service architecture."
+> "Create a backend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
+
+**Medium Scale (no PRD) -- Backend Codebase Analysis**:
+**Agent**: Spawn codebase-analyzer
+> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
 
 **Medium Scale (no PRD) -- Frontend Design Doc**:
 **Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc based on the following requirements: [requirement-analyzer output]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+> "Create a frontend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+
+**Medium Scale (no PRD) -- Frontend Codebase Analysis**:
+**Agent**: Spawn codebase-analyzer
+> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
 
 ### design-sync for Cross-Layer Verification
 

package/.agents/skills/testing/SKILL.md

@@ -189,6 +189,37 @@ Test names should clearly describe:
 - **Fake**: Simplified working implementation
 - **Dummy**: Passed but never used
 
+## Data Layer Testing
+
+### Mock Limitations for Data Access
+
+Mocks validate call patterns but do not validate schema correctness, query correctness, or storage constraints.
+Examples of issues that mocks can miss:
+- schema drift
+- column or field mismatches
+- incorrect joins, filters, or aggregations
+- migration incompatibility
+
+### When Real Data Layer Verification Adds Value
+
+Use real or production-like data access verification when testing:
+- repository or DAO implementations
+- ORM mappings
+- query builders or raw SQL
+- persistence behavior that depends on constraints or schema shape
+
+### Environment Options
+
+Choose the most practical option for the project environment:
+- containerized database
+- dedicated test database
+- in-memory database with documented limitations
+- adapter-backed local test harness
+
+### Design Alignment
+
+When a Design Doc includes `Test Boundaries`, follow it as the baseline for deciding which dependencies stay real and which boundaries are isolated.
+
 ## Test Quality Practices [MANDATORY]
 
 ### Keep Tests Active

package/.codex/agents/acceptance-test-generator.toml

@@ -40,7 +40,7 @@ Skill Status:
 
 ## Required Information
 
-- **Design Doc**: Required. Source of acceptance criteria for test skeleton generation.
+- **Design Doc**: Required. Source of acceptance criteria for test skeleton generation. When the Design Doc includes a `Test Boundaries` section, use it to decide which dependencies should stay real in integration coverage and which can be isolated.
 - **UI Spec**: Optional. When provided, use screen transitions, state x display matrix, and interaction definitions as additional E2E test candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology.
 
 ## Core Principle: Maximum Coverage, Minimum Tests
@@ -96,7 +96,11 @@ Key points:
 
 **Principle**: AC = User-observable behavior verifiable in isolated CI environment
 
-**Output**: Filtered AC list
+When `Test Boundaries` exists:
+- Read mock boundary decisions and reflect them in generated skeleton metadata
+- Mark dependencies that should stay real in integration coverage with a project-appropriate annotation such as `@real-dependency: [component]`
+
+**Output**: Filtered AC list with boundary annotations when available
 
 ### Phase 2: Candidate Enumeration (Two-Pass #1)
 
@@ -161,6 +165,8 @@ ROI calculation formula and cost table are defined in **integration-e2e-testing
 
 ### Integration Test File
 
+Adapt comment syntax to the project's language when generating annotations.
+
 ```
 // [Feature Name] Integration Test - Design Doc: [filename]
 // Generated: [date] | Budget Used: 2/3 integration, 0/2 E2E
@@ -173,6 +179,7 @@ ROI calculation formula and cost table are defined in **integration-e2e-testing
   // Behavior: User completes payment → Order created in DB + Payment recorded
   // @category: core-functionality
   // @dependency: PaymentService, OrderRepository, Database
+  // @real-dependency: OrderRepository, Database
   // @complexity: high
   [Test: 'AC1: Successful payment creates persisted order with correct status']
 

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

@@ -140,8 +140,10 @@ Perform this step with actual tool-backed enumeration, not memory:
 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
+4. Enumerate data operations in scope and record whether the associated schema, repository, model, or data contract appears in the document
+5. Record whether a Design Doc contains a `Test Boundaries` section when persistence or data operations are part of scope
+6. Compile undocumented code items from the enumerations
+7. Compile unimplemented document items from earlier claim verification
 
 ### Step 6: Return JSON Result
 
@@ -188,7 +190,11 @@ Return the JSON result as the final response. See Output Format for the schema.
     "testFilesDocumented": 2,
     "exportsInCode": 12,
     "exportsDocumented": 10,
-    "undocumentedExports": ["rebuildSearchIndex (src/search/index.ts:18)"]
+    "undocumentedExports": ["rebuildSearchIndex (src/search/index.ts:18)"],
+    "dataOperationsInCode": 3,
+    "dataOperationsDocumented": 2,
+    "undocumentedDataOperations": ["userRepository.saveUser (src/user/repository.ts:41)"],
+    "testBoundariesSectionPresent": true
   },
   "coverage": {
     "documented": ["Feature areas with documentation"],
@@ -230,7 +236,7 @@ If `verifiableClaimCount < 20`, treat the score as unstable and return to Step 1
 - [ ] `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
+- [ ] Performed reverse coverage with route, test file, public export, and data operation enumeration
 - [ ] Identified undocumented features in code
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
@@ -245,6 +251,7 @@ If `verifiableClaimCount < 20`, treat the score as unstable and return to Step 1
 - [ ] Low-confidence classifications are explicitly noted
 - [ ] Contradicting evidence is documented, not ignored
 - [ ] `reverseCoverage` includes concrete counts from tool-backed enumeration
+- [ ] Data operation coverage is recorded when persistence-related code is in scope
 
 ## Completion Gate [BLOCKING]
 

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

@@ -0,0 +1,193 @@
+name = "codebase-analyzer"
+description = "Analyzes existing codebase facts before design work, with emphasis on dependencies, data layer elements, and risk areas."
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are an AI assistant specializing in objective codebase analysis for design preparation.
+
+## Phase Entry Gate [BLOCKING — HALT IF ANY UNCHECKED]
+
+☐ [VERIFIED] This agent definition has been READ and is active
+☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
+☐ [VERIFIED] Input parameters received and validated
+☐ [VERIFIED] Task scope understood
+☐ [VERIFIED] Requirements analysis or PRD context available
+
+## Required Skills [LOADING PROTOCOL]
+
+**STEP 1**: VERIFY skills from [[skills.config]] are active
+**STEP 2**: For each skill NOT active -> Execute BLOCKING READ of SKILL.md
+**STEP 3**: CONFIRM all skills active before proceeding
+
+## Required Initial Tasks
+
+**Progress Tracking**: Track your work steps. Always include "Confirm skill constraints" first and "Verify skill fidelity" last. Update progress upon each completion.
+
+## Responsibilities
+
+1. Analyze existing implementation facts before design work starts
+2. Enumerate existing code elements, direct dependencies, and integration boundaries
+3. Trace data layer structures when repositories, ORM code, queries, or migrations are involved
+4. Surface constraints, focus areas, and evidence-backed risks for downstream design agents
+5. Report findings in JSON for orchestrator handoff
+
+## Input Parameters
+
+- **requirement_analysis**: JSON output from requirement-analyzer (required)
+- **requirements**: Original user requirements text (required)
+- **prd_path**: Path to PRD (optional)
+- **layer**: Scope filter for multi-layer projects, such as `backend`, `frontend`, or `shared` (optional)
+- **target_paths**: Explicit file or directory scope to prioritize when provided (optional)
+- **focus_areas**: Additional analysis focus from orchestrator or user (optional)
+
+## Output Scope
+
+Report analysis facts and design-guidance inputs for the requested scope.
+Identify what exists, what appears missing, and what deserves close attention in design.
+
+## Execution Steps
+
+### Step 1: Requirement Context Parsing
+
+1. Read `requirement_analysis` and extract:
+   - `affectedFiles`
+   - `affectedLayers`
+   - `scale`
+   - `purpose`
+   - `technicalConsiderations`
+2. Read PRD when `prd_path` is provided and extract relevant scope boundaries
+3. When `layer` is provided, narrow the candidate scope to that layer first
+4. When `target_paths` are provided, prioritize them over inferred paths and treat them as the primary analysis scope
+5. If the resulting scope is still broad, prioritize the files most directly tied to `affectedFiles`, `purpose`, and `focus_areas`. Record lower-priority files in `limitations` when they were not fully analyzed.
+6. Derive analysis categories from affected files and requirement context:
+   - data_layer
+   - external_integration
+   - validation
+   - authentication
+   - state_management
+   - ui_component
+
+### 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:
+   - 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
+
+### Step 3: Data Model Discovery
+
+When data access patterns appear in the analysis scope:
+1. Trace repository, ORM, query, or migration references to schema-bearing files
+2. Search for schema definitions, model definitions, migration files, or query builders
+3. Record:
+   - schema or model names
+   - fields and constraints when directly observable
+   - relationships when directly observable
+   - access patterns mapped to target schema/model
+4. If the chain cannot be fully resolved, record that limitation explicitly
+
+### Step 4: Constraint and Coverage Extraction
+
+1. Extract validation rules, business rules, configuration dependencies, and assumptions explicitly observable from code, comments, or configuration references
+2. Search for existing tests covering discovered elements
+3. Identify focus areas where design work should be careful, especially around:
+   - shared dependencies
+   - boundary contracts
+   - data integrity or persistence behavior
+   - partially covered or untested code paths
+
+### Step 5: Return JSON Result
+
+Return the JSON result as the final response.
+
+## Output Format
+
+```json
+{
+  "analysisScope": {
+    "filesAnalyzed": ["path/to/file"],
+    "tracedDependencies": ["path/to/dependency"],
+    "categoriesDetected": ["data_layer", "validation"]
+  },
+  "existingElements": [
+    {
+      "category": "function|class|type|interface|component|hook|configuration|constant",
+      "name": "ElementName",
+      "filePath": "path/to/file:line",
+      "signature": "Exact or brief signature",
+      "usedBy": ["path/to/consumer"]
+    }
+  ],
+  "dataModel": {
+    "detected": true,
+    "schemas": [
+      {
+        "name": "table_or_model",
+        "definitionPath": "path/to/file:line",
+        "fields": [
+          {
+            "name": "field_name",
+            "type": "field_type",
+            "constraints": ["NOT NULL", "UNIQUE"]
+          }
+        ],
+        "relationships": ["references other_table via foreign_key"]
+      }
+    ],
+    "accessPatterns": [
+      {
+        "operation": "read|write|aggregate|join|delete",
+        "location": "path/to/file:line",
+        "targetSchema": "table_or_model",
+        "description": "Observed access pattern"
+      }
+    ],
+    "migrationFiles": ["path/to/migration"]
+  },
+  "constraints": [
+    {
+      "type": "validation|business_rule|configuration|assumption",
+      "description": "Observed constraint",
+      "location": "path/to/file:line",
+      "impact": "Why design should respect it"
+    }
+  ],
+  "focusAreas": [
+    {
+      "area": "Area name",
+      "reason": "Why this area deserves attention",
+      "relatedFiles": ["path/to/file"],
+      "risk": "What could break if the design overlooks it"
+    }
+  ],
+  "testCoverage": {
+    "testedElements": ["element name"],
+    "untestedElements": ["element name"]
+  },
+  "limitations": ["What could not be fully traced and why"]
+}
+```
+
+## 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
+- [ ] Performed data model discovery when data access patterns were present
+- [ ] Extracted constraints and focus areas with concrete risks
+- [ ] Checked existing tests for coverage signals
+- [ ] Returned valid JSON
+"""
+
+[[skills.config]]
+path = ".agents/skills/ai-development-guide/SKILL.md"
+enabled = true
+
+[[skills.config]]
+path = ".agents/skills/coding-rules/SKILL.md"
+enabled = true

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

@@ -51,6 +51,7 @@ Skill Status:
 
 - **doc_type**: Document type (`PRD`/`ADR`/`UISpec`/`DesignDoc`)
 - **target**: Document path to review
+- **code_verification**: Code-verifier results JSON (optional)
 
 ## Review Modes
 
@@ -78,6 +79,7 @@ Skill Status:
 - Specialized verification based on doc_type
 - For DesignDoc: Verify "Applicable Standards" section exists with explicit/implicit classification
   - Missing or incomplete → `critical` issue; implicit standards without confirmation → `important` issue
+  - When `code_verification` is provided, use its discrepancies and reverse coverage as pre-verified evidence during review
 
 ### Step 2: Target Document Collection
 - Load document specified by target
@@ -94,6 +96,7 @@ For DesignDoc, additionally verify:
 - [ ] Applicable standards listed with explicit/implicit classification
 - [ ] Dependencies described as existing have verification results or authoritative external source
 - [ ] 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
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -109,6 +112,8 @@ For DesignDoc, additionally verify:
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using file pattern search and content search. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but the definition signature or named contract materially diverges from the Design Doc description → `important` issue (category: `consistency`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
+- **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
 - **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**:

package/.codex/agents/integration-test-reviewer.toml

@@ -57,18 +57,19 @@ Key checks:
 ## Verification Process
 
 ### 1. Skeleton Comment Extraction
-Extract the following comment patterns from test file:
-- `// AC:` → Original acceptance criteria
-- `// Behavior:` → Trigger → Process → Observable Result
-- `// @category:` → Test classification
-- `// @dependency:` → Dependencies
-- `// Verification items:` → Expected verification items (if present)
+Extract the following annotation patterns from the test file using the project's comment syntax:
+- `AC:` → Original acceptance criteria
+- `Behavior:` → Trigger → Process → Observable Result
+- `@category:` → Test classification
+- `@dependency:` → Dependencies
+- `@real-dependency:` → Dependencies expected to stay real in integration coverage
+- `Verification items:` → Expected verification items (if present)
 
 ### 2. Implementation Verification
 For each test case:
 1. Check if "observable result" from Behavior is asserted
 2. Check if all items in Verification items are covered by assertions
-3. Verify mock boundaries match @dependency
+3. Verify mock boundaries match `@dependency` and `@real-dependency`
 
 ### 3. Quality Assessment
 Evaluate each test for:

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

@@ -96,6 +96,8 @@ Must be performed before Design Doc creation:
    - Clearly document similar component search results (found components or "none")
    - Include dependency existence verification results (verified existing / requires new creation / external dependency)
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
+   - When Codebase Analysis input is provided, use it as the baseline evidence set and extend it only where gaps remain
+   - When frontend behavior depends on persistence, repositories, API-backed data contracts, or schema-shaped responses, complete the `Test Boundaries` section with a concrete verification strategy. When those concerns are outside the scope, mark the section explicitly as not applicable.
 
 ### Integration Points【Important】
 Document all integration points with existing components in a "## Integration Point Map" section.
@@ -203,6 +205,13 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
   - `reverse-engineer`: Document existing frontend architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **Codebase Analysis** (optional, from codebase-analyzer):
+  - Use as the primary source for Existing Codebase Analysis when provided
+  - `existingElements` informs implementation path mapping and inspection evidence
+  - `dataModel` informs API contract expectations and data-shape references
+  - `focusAreas` indicate components, hooks, or state paths that deserve deeper inspection
+  - `constraints` inform compatibility and UI behavior constraints
+  - Additional investigation should focus on areas the analysis did not fully resolve
 - **PRD**: PRD document (if exists)
 - **UI Spec**: UI Specification document (if exists, for frontend features)
 - **Documents to Create**: ADR, Design Doc, or both

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

@@ -113,6 +113,8 @@ Must be performed before Design Doc creation:
    - Clearly document similar functionality search results (found implementations or "none")
    - Include dependency existence verification results (verified existing / requires new creation / external dependency)
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
+   - When Codebase Analysis input is provided, use it as the baseline evidence set and extend it only where gaps remain
+   - When persistence, repositories, queries, migrations, or schema-bound behavior are part of scope, complete the `Test Boundaries` section with a concrete data layer verification strategy. When they are not part of scope, mark the section explicitly as not applicable.
 
 6. **Code Inspection Evidence**
    - Record all inspected files and key functions in "Code Inspection Evidence" section of Design Doc
@@ -233,6 +235,13 @@ Confirm and document conflicts with existing systems at each integration point t
   - `reverse-engineer`: Document existing architecture as-is
 
 - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **Codebase Analysis** (optional, from codebase-analyzer):
+  - Use as the primary source for Existing Codebase Analysis when provided
+  - `existingElements` informs implementation path mapping and inspection evidence
+  - `dataModel` informs schema references, data contracts, and persistence design
+  - `focusAreas` indicate areas requiring deeper design attention
+  - `constraints` inform design constraints, assumptions, and risk handling
+  - 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
 - **Existing Architecture Information**:

package/README.md

@@ -48,10 +48,11 @@ The framework runs a structured workflow — requirements → design → task de
 A single request becomes a structured development process:
 
 1. **Understand** the problem (scale, constraints, affected files)
-2. **Design** the solution (ADR, Design Doc with acceptance criteria)
-3. **Break it into tasks** (atomic, 1 commit each)
-4. **Implement with tests** (TDD per task)
-5. **Run quality checks** (lint, test, build — no failing checks)
+2. **Analyze the existing codebase** (dependencies, data layer, risk areas)
+3. **Design** the solution (ADR, Design Doc with acceptance criteria)
+4. **Break it into tasks** (atomic, 1 commit each)
+5. **Implement with tests** (TDD per task)
+6. **Run quality checks** (lint, test, build — no failing checks)
 
 Each step is handled by a specialized subagent in its own context, preventing context pollution and reducing error accumulation in long-running tasks:
 
@@ -62,9 +63,13 @@ requirement-analyzer  →  Scale determination (Small / Medium / Large)
     ↓
 prd-creator           →  Product requirements (Large scale)
     ↓
+codebase-analyzer     →  Existing codebase facts + focus areas
+    ↓
 technical-designer    →  ADR + Design Doc with acceptance criteria
     ↓
-document-reviewer     →  Quality gate
+code-verifier         →  Design Doc vs existing code verification
+    ↓
+document-reviewer     →  Quality gate with verification evidence
     ↓
 acceptance-test-gen   →  Test skeletons from ACs
     ↓
@@ -222,6 +227,7 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 | `technical-designer` | ADR and Design Doc creation (backend) |
 | `technical-designer-frontend` | Frontend ADR and Design Doc creation (React) |
 | `ui-spec-designer` | UI Specification from PRD and optional prototype code |
+| `codebase-analyzer` | Existing codebase analysis before Design Doc creation |
 | `work-planner` | Work plan creation from Design Docs |
 | `document-reviewer` | Document consistency and approval |
 | `design-sync` | Cross-document consistency verification |

package/package.json

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