codex-workflows 0.3.1 → 0.4.1

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

@@ -7,9 +7,7 @@ description: "Guides subagent coordination through implementation workflows. Use
 
 ## Role: The Orchestrator
 
-**The orchestrator coordinates subagents like a conductor -- directing the musicians without playing the instruments.**
-
-All investigation, analysis, and implementation work flows through specialized subagents.
+The orchestrator coordinates subagents. All investigation, analysis, and implementation work flows through specialized subagents.
 
 ### Prompt Construction Rule
 Every subagent prompt must include:
@@ -65,13 +63,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 +105,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 +178,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 +217,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 +226,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
 
@@ -299,18 +315,11 @@ Stop autonomous execution and escalate to user in the following cases:
 3. **Work-planner update restriction violated**: Requirement changes after task-decomposer starts require overall redesign
 4. **User explicitly stops**: Direct stop instruction or interruption
 
-### Task Management: 4-Step Cycle
-
-**Per-task cycle**:
-1. task-executor: Implementation
-2. Check task-executor response:
-   - `escalation_needed` or `blocked`: Escalate to user
-   - `requiresTestReview` is `true`: Execute integration-test-reviewer
-     - `needs_revision`: Return to step 1 with requiredFixes
-     - `approved`: Proceed to step 3
-   - Otherwise: Proceed to step 3
-3. quality-fixer: Quality check and fixes
-4. git commit (on `status: "approved"`)
+Use the task loop defined in the autonomous execution diagram above. The canonical per-task cycle is:
+1. task-executor implementation
+2. escalation or integration-test-reviewer decision
+3. quality-fixer quality gate
+4. git commit on approval
 
 ## Main Orchestrator Roles
 
@@ -341,13 +350,27 @@ Stop autonomous execution and escalate to user in the following cases:
 
 **On error**: Escalate to user if files are not generated
 
+### Design Doc to Work Plan Verification Handoff
+
+When a Design Doc contains a Verification Strategy section, the orchestrator must carry forward:
+- Design Doc path
+- Verification Strategy details:
+  - Correctness definition
+  - Target comparison
+  - Verification method
+  - Observable success indicator
+  - Verification timing
+  - Early verification point (first target, success criteria, failure response)
+
+The resulting work plan must include this summary in its header so the plan remains self-sufficient for downstream task generation and execution planning.
+
 ## Important Constraints [MANDATORY]
 
 - **Quality check is REQUIRED**: quality-fixer approval MUST be obtained before commit
 - **Structured response REQUIRED**: Information transmission between subagents MUST use JSON format
 - **Approval management**: Document creation -> Execute document-reviewer -> Get user approval before proceeding
 - **Flow confirmation**: After getting approval, MUST check next step with work planning flow (large/medium/small scale)
-- **Consistency verification**: If subagent determinations contradict, MUST prioritize guidelines
+- **Consistency verification**: If subagent determinations contradict, MUST prioritize the constraints and decision rules defined in this orchestration guide
 
 **ENFORCEMENT**: Violating ANY constraint requires immediate correction
 
@@ -362,9 +385,9 @@ Stop autonomous execution and escalate to user in the following cases:
 
 When receiving a task, check the following:
 
-- [ ] Confirmed if there is an orchestrator instruction
+- [ ] Confirmed whether the user provided a specific workflow recipe or explicit execution constraint
 - [ ] Determined task type (new feature/fix/research, etc.)
-- [ ] Considered appropriate subagent utilization
+- [ ] Selected the next subagent according to the decision flow and current phase
 - [ ] Decided next action according to decision flow
 - [ ] Monitored requirement changes and errors during autonomous execution mode
 

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,8 @@ 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
+- [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -109,6 +113,9 @@ 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
+- **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase
 - **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**:
@@ -250,6 +257,8 @@ Include in output when `prior_context_count > 0`:
 
 - [ ] Match of requirements, terminology, numbers between documents
 - [ ] Completeness of required elements in each document
+- [ ] Verification Strategy present with a concrete correctness definition and early verification point
+- [ ] Verification Strategy aligns with design type and implementation approach
 - [ ] Compliance with project rules
 - [ ] Technical feasibility and reasonableness of estimates
 - [ ] Clarification of risks and countermeasures