codex-workflows 0.3.0 → 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/documentation-criteria/references/task-template.md

@@ -13,8 +13,17 @@ Metadata:
 - [ ] [Implementation file path]
 - [ ] [Test file path]
 
+## Investigation Targets
+Files to read before starting implementation. Use concrete file paths, optionally with a section/function hint:
+- [e.g., src/orders/checkout.ts (processOrder function)]
+
+## Investigation Notes
+Brief observations recorded after reading Investigation Targets:
+- [path] - [interfaces, control/data flow, state transitions, side effects relevant to this task]
+
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
+- [ ] Read all Investigation Targets and update Investigation Notes
 - [ ] Review dependency deliverables (if any)
 - [ ] Verify/create contract definitions
 - [ ] Write failing tests

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:
@@ -73,6 +76,19 @@ When verification points need explicit enumeration:
 // - [Item 2]
 ```
 
+### E2E Preconditions (Optional but Recommended)
+
+When an E2E test requires environment setup, seed data, login state, or external dependency control, annotate it explicitly:
+
+```text
+// Preconditions:
+// - Seeded user with active subscription
+// - Authenticated browser session
+// - Payment provider mocked or available in local environment
+```
+
+These annotations allow work-planner to create prerequisite tasks before E2E execution.
+
 ## EARS Format Mapping
 
 | EARS Keyword | Test Type | Generation Approach |
@@ -97,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
-- **task-executor**: status (escalation_needed/blocked/completed), testsAdded, requiresTestReview
-- **quality-fixer**: status (approved/blocked)
+- **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]