codex-workflows 0.2.0 → 0.2.2

package/.agents/skills/coding-rules/references/security-checks.md

@@ -14,17 +14,17 @@ These patterns have low false-positive rates and are detectable through grep or
 
 ### SQL String Concatenation
 - SQL statements constructed through string concatenation or interpolation with variables
-- Detection approach: search for SQL keywords (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) combined with string concatenation operators or template literals containing variable references
+- Detection approach: search for SQL keywords (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) combined with string concatenation operators or string interpolation containing variable references
 
 ### Dynamic Code Execution
-- Use of `eval()`, `Function()`, `exec()`, `compile()` with dynamic input
-- Dynamic import or require with variable paths
-- Detection approach: search for these function calls where the argument is not a static literal
+- Use of dynamic code execution functions (e.g., `eval`, `exec`) with non-static input
+- Dynamic module loading with variable paths
+- Detection approach: search for dynamic code execution or module loading calls where the argument is not a static literal
 
 ### Insecure Deserialization
-- `pickle.loads()`, `yaml.load()` without SafeLoader, `marshal.loads()` with untrusted input
-- `JSON.parse()` followed by direct use in `eval()` or `Function()`
-- Detection approach: search for deserialization calls that accept external input without safe loader configuration
+- Deserialization of untrusted input using unsafe loaders or formats that allow arbitrary object construction (e.g., native serialization, YAML without safe loader)
+- Parsed data passed directly into dynamic code execution
+- Detection approach: search for deserialization calls that accept external input without safe loader or type-restricted configuration
 
 ### Path Traversal
 - File system paths constructed from user-supplied input without sanitization

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

@@ -179,12 +179,12 @@ No Ripple Effect:
 
 ```yaml
 Input:
-  Type: [Type/interface definition]
+  Type: [Data shape, contract, or schema]
   Preconditions: [Required items, format constraints]
   Validation: [Validation method]
 
 Output:
-  Type: [Type/interface definition]
+  Type: [Data shape, contract, or schema]
   Guarantees: [Conditions that must always be met]
   On Error: [Exception/null/default value]
 

package/.agents/skills/recipe-add-integration-tests/SKILL.md

@@ -109,11 +109,11 @@ Check Step 5 result:
 
 Spawn quality-fixer agent: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage."
 
-**Expected output**: `approved` (true/false)
+**Expected output**: `status` (`approved`/`blocked`)
 
 ### Step 8: Commit
 
-On `approved: true` from quality-fixer:
+On `status: "approved"` from quality-fixer:
 - MUST commit test files with appropriate message
 ENFORCEMENT: Commits without quality-fixer approval are invalid.
 

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

@@ -80,7 +80,7 @@ For EACH task, YOU MUST:
      - `approved` -> Proceed to step 4
    - `readyForQualityCheck: true` -> Proceed to step 4
 4. **Spawn quality-fixer agent**: "Execute all quality checks and fixes"
-5. **COMMIT on approval**: After `approved: true` from quality-fixer -> Execute git commit
+5. **COMMIT on approval**: After `status: "approved"` from quality-fixer -> Execute git commit
 
 **CRITICAL**: MUST monitor ALL structured responses WITHOUT EXCEPTION and ENSURE every quality gate is passed.
 ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent work.

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

@@ -74,7 +74,7 @@ Verify generated task files exist in docs/plans/tasks/.
 Each sub-agent responds in JSON format:
 - **task-executor-frontend**: status, filesModified, testsAdded, requiresTestReview, readyForQualityCheck
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
-- **quality-fixer-frontend**: status, checksPerformed, fixesApplied, approved
+- **quality-fixer-frontend**: status, checksPerformed, fixesApplied
 
 ### Execution Flow for Each Task
 
@@ -88,7 +88,7 @@ For EACH task, YOU MUST:
      - `approved` -> Proceed to step 4
    - `readyForQualityCheck: true` -> Proceed to step 4
 4. **Spawn quality-fixer-frontend agent**: "Execute all frontend quality checks and fixes"
-5. **COMMIT on approval**: After `approved: true` from quality-fixer-frontend -> Execute git commit. Use `changeSummary` for commit message.
+5. **COMMIT on approval**: After `status: "approved"` from quality-fixer-frontend -> Execute git commit. Use `changeSummary` for commit message.
 
 **CRITICAL**: MUST monitor ALL structured responses WITHOUT EXCEPTION and ENSURE every quality gate is passed.
 ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent work.

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

@@ -98,7 +98,7 @@ For EACH task, YOU MUST:
      - `approved` -> Proceed to step 4
    - `readyForQualityCheck: true` -> Proceed to step 4
 4. **Spawn quality-fixer agent** (layer-appropriate per routing table): "Execute all quality checks and fixes"
-5. **COMMIT on approval**: After `approved: true` from quality-fixer -> Execute git commit
+5. **COMMIT on approval**: After `status: "approved"` from quality-fixer -> Execute git commit
 
 **CRITICAL**: MUST monitor ALL structured responses WITHOUT EXCEPTION and ENSURE every quality gate is passed.
 ENFORCEMENT: Proceeding past a failed quality gate invalidates all subsequent work.

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

@@ -123,7 +123,7 @@ ENFORCEMENT: Sub-agent prompts missing the constraint suffix MUST be re-issued w
 1. Execute ONE task completely before starting next (each task goes through the full 4-step cycle individually, using the correct executor per filename pattern)
 2. Check executor status before quality-fixer (escalation check)
 3. Quality-fixer MUST run after each executor (no skipping)
-4. Commit MUST execute when quality-fixer returns `approved: true` (do not defer to end)
+4. Commit MUST execute when quality-fixer returns `status: "approved"` (do not defer to end)
 
 ### Security Review (After All Tasks Complete)
 

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

@@ -106,7 +106,7 @@ After user grants "batch approval for entire implementation phase", enter autono
      - `approved` -> Proceed to step 3
    - Otherwise -> Proceed to step 3
 3. Spawn quality-fixer (or quality-fixer-frontend) agent: "Quality check and fixes"
-4. git commit -> Execute on `approved: true`
+4. git commit -> Execute on `status: "approved"`
 
 ### Security Review (After All Tasks Complete)
 

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

@@ -20,7 +20,7 @@ Target: $ARGUMENTS
 **Execution Protocol**:
 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
 2. **Process one step at a time**: Execute steps sequentially within each unit (2 -> 3 -> 4 -> 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next
-3. **Pass `$STEP_N_OUTPUT` as-is** to sub-agents -- the orchestrator bridges data without processing or filtering it
+3. **Pass `$STEP_N_OUTPUT` as-is** to sub-agents -- the orchestrator bridges data without processing or filtering it, except for steps that explicitly define a deterministic transformation with an input schema, output schema, and mapping rules
 
 **Task Registration**: Register phases first, then steps within each phase as you enter it. Track status for each step.
 
@@ -44,7 +44,7 @@ Ask the user to confirm:
 
 ```
 Phase 1: PRD Generation
-  Step 1: Scope Discovery (unified, single pass)
+  Step 1: Scope Discovery (unified, single pass -> group into PRD units -> human review)
   Step 2-5: Per-unit loop (Generation -> Verification -> Review -> Revision)
 
 Phase 2: Design Doc Generation (if requested)
@@ -67,17 +67,19 @@ Spawn scope-discoverer agent: "Discover functional scope targets in the codebase
 **Quality Gate**:
 - At least one unit discovered -> proceed
 - No units discovered -> ask user for hints
+- `$STEP_1_OUTPUT.prdUnits` exists
+- All `sourceUnits` across `prdUnits` (flattened, deduplicated) match the set of `discoveredUnits` IDs — no unit missing, no unit duplicated
 
-**[STOP — BLOCKING]** If human review enabled: Present discovered units to user for confirmation.
+**[STOP — BLOCKING]** If human review enabled: Present `$STEP_1_OUTPUT.prdUnits` with their source unit mapping to user for confirmation.
 **CANNOT proceed until user explicitly confirms.**
 
 ### Step 2-5: Per-Unit Processing
 
-**FOR** each unit in `$STEP_1_OUTPUT.discoveredUnits` **(sequential, one unit at a time)**:
+**FOR** each unit in `$STEP_1_OUTPUT.prdUnits` **(sequential, one unit at a time)**:
 
 #### Step 2: PRD Generation
 
-Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Related Files: $UNIT_RELATED_FILES. Entry Points: $UNIT_ENTRY_POINTS. Skip independent scope discovery. Use provided scope data. Create final version PRD based on code investigation within specified scope."
+Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRD_UNIT_NAME. Description: $PRD_UNIT_DESCRIPTION. Related Files: $PRD_UNIT_COMBINED_RELATED_FILES. Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS. Source Units: $PRD_UNIT_SOURCE_UNITS. Skip independent scope discovery. Use provided scope data. Create final version PRD based on code investigation within specified scope."
 
 **Store output as**: `$STEP_2_OUTPUT` (PRD path)
 
@@ -85,7 +87,7 @@ Spawn prd-creator agent: "Create reverse-engineered PRD for the following featur
 
 **Prerequisite**: $STEP_2_OUTPUT (PRD path from Step 2)
 
-Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. code_paths: $UNIT_RELATED_FILES. verbose: false."
+Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. code_paths: $PRD_UNIT_COMBINED_RELATED_FILES. verbose: false."
 
 **Store output as**: `$STEP_3_OUTPUT`
 
@@ -130,11 +132,21 @@ ENFORCEMENT: Exceeding 2 revision cycles without flagging produces unreviewed ou
 
 ### Step 6: Design Doc Scope Mapping
 
-**No additional discovery required.** Use `$STEP_1_OUTPUT` (scope discovery results) directly.
+**Step type**: Deterministic transformation step executed by the orchestrator.
 
-Each PRD unit from Phase 1 maps to one Design Doc unit (using technical-designer).
+**No additional discovery required.** Use `$STEP_1_OUTPUT.discoveredUnits` (implementation-granularity units) for technical profiles. Use `$STEP_1_OUTPUT.prdUnits[].sourceUnits` to trace which discovered units belong to each PRD unit.
 
-Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward:
+**Default mapping rule**: Each PRD unit maps to exactly 1 Design Doc unit.
+
+Only split one PRD unit into multiple Design Doc units when BOTH are true:
+1. The source units contain clearly separate technical boundaries with low shared-file overlap
+2. Separate Design Docs would improve verification clarity (different public interfaces, dependencies, or module groups)
+
+If the split conditions are not clearly met, keep 1 PRD unit -> 1 Design Doc unit.
+
+Transform `$STEP_1_OUTPUT` into `$STEP_6_OUTPUT` using only the mapping rules in this step.
+
+Map PRD units to Design Doc generation targets by resolving each PRD unit's `sourceUnits` back to `$STEP_1_OUTPUT.discoveredUnits`, carrying forward:
 - `technicalProfile.primaryModules` -> Primary Files
 - `technicalProfile.publicInterfaces` -> Public Interfaces
 - `dependencies` -> Dependencies
@@ -142,6 +154,30 @@ Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward:
 
 **Store output as**: `$STEP_6_OUTPUT`
 
+`$STEP_6_OUTPUT` MUST be a JSON array of Design Doc generation targets in the following shape:
+
+```json
+[
+  {
+    "unitId": "DD-001",
+    "parentPrdUnitId": "PRD-001",
+    "unitName": "Authentication",
+    "unitDescription": "Current implementation for sign-in and session management",
+    "sourceUnits": ["UNIT-001", "UNIT-002"],
+    "primaryModules": ["src/auth/service.ts", "src/auth/controller.ts"],
+    "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
+    "dependencies": ["UNIT-003"],
+    "scopeBoundary": ["src/auth/*"],
+    "mappingRationale": "Default 1:1 mapping from PRD unit because technical scope is cohesive"
+  }
+]
+```
+
+**Quality Gate**:
+- Every PRD unit appears in at least one `$STEP_6_OUTPUT` item
+- Every `$STEP_6_OUTPUT` item references only discovered units from its parent PRD unit
+- `mappingRationale` explicitly states whether the mapping is default 1:1 or an intentional split
+
 ### Step 7-10: Per-Unit Processing
 
 **FOR** each unit in `$STEP_6_OUTPUT` **(sequential, one unit at a time)**:

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

@@ -31,7 +31,7 @@ ENFORCEMENT: Skipping document-reviewer risks propagating inconsistencies to dow
 ```
 Target document -> [Stop: Confirm changes]
                         |
-              technical-designer / prd-creator (update mode)
+              technical-designer / technical-designer-frontend / prd-creator (update mode)
                         |
               document-reviewer -> [Stop: Review approval]
                         | (Design Doc only)
@@ -70,15 +70,20 @@ Check for existing documents in docs/design/, docs/prd/, docs/adr/.
 | Multiple candidates found | Present options to user |
 | No documents found | Report and end (suggest $recipe-design instead) |
 
-### Step 2: Document Type Determination
+### Step 2: Document Type and Layer Determination
 
-Determine type from document path:
+Determine type from document path, then determine the layer to select the correct update agent:
 
 | Path Pattern | Type | Update Agent | Notes |
 |-------------|------|--------------|-------|
-| `docs/design/*.md` | Design Doc | technical-designer | - |
+| `docs/design/*.md` | Design Doc | technical-designer or technical-designer-frontend | See layer detection below |
 | `docs/prd/*.md` | PRD | prd-creator | - |
-| `docs/adr/*.md` | ADR | technical-designer | Minor changes: update existing file; Major changes: create new ADR file |
+| `docs/adr/*.md` | ADR | technical-designer or technical-designer-frontend | See layer detection below |
+
+**Layer detection** (for Design Doc and ADR):
+Read the document and determine its layer from content signals:
+- **Frontend** (-> technical-designer-frontend): Document title/scope mentions React, components, UI, frontend; or file contains component hierarchy, state management, UI interactions
+- **Backend** (-> technical-designer): All other cases (API, data layer, business logic, infrastructure)
 
 **ADR Update Guidance**:
 - **Minor changes** (clarification, typo fix, small scope adjustment): Update the existing ADR file

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

@@ -173,10 +173,10 @@ All agents MUST use this vocabulary consistently:
 
 ## Structured Response Specification
 
-Subagents respond in JSON format. Key fields for orchestrator decisions:
+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**: approved (true/false)
+- **quality-fixer**: status (approved/blocked)
 - **document-reviewer**: verdict.decision (approved/approved_with_conditions/needs_revision/rejected)
 - **design-sync**: sync_status (CONFLICTS_FOUND/NO_CONFLICTS) — text format with [SUMMARY] block
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
@@ -310,7 +310,7 @@ Stop autonomous execution and escalate to user in the following cases:
      - `approved`: Proceed to step 3
    - Otherwise: Proceed to step 3
 3. quality-fixer: Quality check and fixes
-4. git commit (on `approved: true`)
+4. git commit (on `status: "approved"`)
 
 ## Main Orchestrator Roles
 

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

@@ -99,13 +99,13 @@ Each task uses the standard 4-step cycle with layer-appropriate agents:
 1. task-executor: Implementation
 2. Escalation check
 3. quality-fixer: Quality check and fixes
-4. git commit (on approved: true)
+4. git commit (on status: "approved")
 
 ### frontend-task
 1. task-executor-frontend: Implementation
 2. Escalation check
 3. quality-fixer-frontend: Quality check and fixes
-4. git commit (on approved: true)
+4. git commit (on status: "approved")
 
 ### integration-test-reviewer Placement
 

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

@@ -89,11 +89,14 @@ Verify against the Design Doc architecture:
 - No unnecessary duplicate implementations (Pattern 5 from ai-development-guide skill)
 - Existing codebase analysis section includes similar functionality investigation results
 
-### 5. Calculate Compliance and Produce Report
+### 5. Calculate Compliance
 - Compliance rate = (fulfilled items + 0.5 x partially fulfilled items) / total AC items x 100
 - Compile all AC statuses, quality issues with specific locations
 - Determine verdict based on compliance rate
 
+### 6. Return JSON Result
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 ```json
@@ -136,6 +139,13 @@ Verify against the Design Doc architecture:
 - Provide solutions, not just problems; quantify wherever possible
 - Acknowledge good implementations; present improvements as actionable items
 
+## Completion Criteria
+
+- [ ] All acceptance criteria individually evaluated
+- [ ] Compliance rate calculated
+- [ ] Verdict determined
+- [ ] Final response is the JSON output
+
 ### Escalation Criteria
 Recommend higher-level review when: Design Doc itself has deficiencies, security concerns discovered, or critical performance issues found.
 

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

@@ -78,7 +78,7 @@ Document modification and solution proposals are out of scope for this agent.
 | Implementation | 1 | Direct code implementing the claim |
 | Tests | 2 | Test cases verifying expected behavior |
 | Config | 3 | Configuration files, environment variables |
-| Types | 4 | Type definitions, interfaces, schemas |
+| Types & Contracts | 4 | Type definitions, schemas, API contracts |
 
 MUST collect from at least 2 sources before classifying. Single-source findings MUST be marked with lower confidence.
 
@@ -136,6 +136,10 @@ For each claim with collected evidence:
 2. **Implementation Coverage**: What percentage of specs are implemented?
 3. List undocumented features and unimplemented specs
 
+### Step 6: Return JSON Result
+
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 **JSON format is mandatory.**
@@ -201,7 +205,7 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 - [ ] Identified undocumented features in code
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
-- [ ] Output in specified format
+- [ ] Final response is the JSON output
 
 ## Output Self-Check
 - [ ] All findings are based on verification evidence (no modifications proposed)

package/.codex/agents/design-sync.toml

@@ -185,19 +185,17 @@ ENFORCEMENT: sync_status MUST be one of: CONFLICTS_FOUND | NO_CONFLICTS | SKIPPE
 
 ### Type Definition Mismatch
 ```
-// Source Design Doc
-interface User {
+Source Design Doc:
+User
   id: string
   email: string
-  role: 'admin' | 'user'
-}
+  role: admin | user
 
-// Other Design Doc (conflict)
-interface User {
-  id: number        // different type
+Other Design Doc (conflict):
+User
+  id: number        # different type
   email: string
-  userRole: string  // different property name and type
-}
+  userRole: string  # different property name and type
 ```
 
 ### Numeric Parameter Mismatch

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

@@ -127,13 +127,15 @@ Checklist:
 - [ ] If prior_context_count > 0: Each item has resolution status
 - [ ] If prior_context_count > 0: `prior_context_check` object prepared
 - [ ] Output is valid JSON
+- [ ] Final response is the JSON output
 
 Complete all items before proceeding to output.
 
-### Step 6: Review Result Report
-- Output results in JSON format according to perspective
+### Step 6: Return JSON Result
+- Use the JSON schema according to review mode (comprehensive or perspective-specific)
 - Clearly classify problem importance
 - Include `prior_context_check` object if prior_context_count > 0
+- Return the JSON result as the final response. See Output Format for the schema.
 
 ## Output Format
 

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

@@ -78,6 +78,9 @@ Evaluate each test for:
 - No shared state
 - No time-dependent logic
 
+### 4. Return JSON Result
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 ```json
@@ -137,6 +140,7 @@ Evaluate each test for:
 - [ ] No test interdependencies
 - [ ] Deterministic execution (no random/time dependency)
 - [ ] Test name matches verification content
+- [ ] Final response is the JSON output
 
 ## Common Issues and Fixes
 

package/.codex/agents/investigator.toml

@@ -90,12 +90,15 @@ Information source priority:
 - Stopping at "~ is not configured" → without tracing why it's not configured
 - Stopping at technical element names → without tracing why that state occurred
 
-### Step 4: Impact Scope Identification and Output
+### Step 4: Impact Scope Identification
 
 - Search for locations implemented with the same pattern (impactScope)
 - Determine recurrenceRisk: low (isolated) / medium (2 or fewer locations) / high (3+ locations or design_gap)
 - Disclose unexplored areas and investigation limitations
-- Output in JSON format
+
+### Step 5: Return JSON Result
+
+Return the JSON result as the final response. See Output Format for the schema.
 
 ## Evidence Strength Classification
 
@@ -173,6 +176,7 @@ Information source priority:
 - [ ] Enumerated 2+ hypotheses with causal tracking, evidence collection, and causeCategory determination for each
 - [ ] Determined impactScope and recurrenceRisk
 - [ ] Documented unexplored areas and investigation limitations
+- [ ] Final response is the JSON output
 
 ## Output Self-Check
 - [ ] Multiple hypotheses were evaluated (not just the first plausible one)

package/.codex/agents/quality-fixer-frontend.toml

@@ -69,8 +69,13 @@ Apply fixes following the principles in coding-rules skill and testing skill.
 **Step 4: Repeat Until Approved**
 - Address all errors in each phase before proceeding to next phase
 - Error found → Fix immediately → Re-run checks
-- All pass → Return `approved: true`
-- Cannot determine spec → Return `blocked`
+- All pass → proceed to Step 5
+- Cannot determine spec → proceed to Step 5 with `blocked` status
+
+**Step 5: Return JSON Result**
+Return one of the following as the final response (see Output Format for schemas):
+- `status: "approved"` — all quality checks pass
+- `status: "blocked"` — specification unclear, business judgment required
 
 ## Frontend-Specific Quality Criteria
 
@@ -174,7 +179,6 @@ Before setting status to blocked, confirm specifications in this order:
     "totalWarnings": 0,
     "executionTime": "3m 30s"
   },
-  "approved": true,
   "nextActions": "Ready to commit"
 }
 ```
@@ -200,11 +204,9 @@ Before setting status to blocked, confirm specifications in this order:
 }
 ```
 
-### User Report (Mandatory)
-
-Summarize quality check results in an understandable way for users
+## Intermediate Progress Report
 
-### Phase-by-phase Report (Detailed Information)
+During execution, report progress between tool calls using this format:
 
 ```markdown
 Phase [Number]: [Phase Name]
@@ -222,6 +224,12 @@ Issues requiring fixes:
 Phase [Number] Complete! Proceeding to next phase.
 ```
 
+This is intermediate output only. The final response must be the JSON result (Step 5).
+
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `approved` or `blocked`
+
 ## Important Principles
 
 MUST follow these principles to maintain high-quality React code:

package/.codex/agents/quality-fixer.toml

@@ -66,8 +66,13 @@ Apply fixes following the principles in coding-rules skill and testing skill.
 **Step 4: Repeat Until Approved**
 - Address all errors in each phase before proceeding to next phase
 - Error found → Fix immediately → Re-run checks
-- All pass → Return `approved: true`
-- Cannot determine spec → Return `blocked`
+- All pass → proceed to Step 5
+- Cannot determine spec → proceed to Step 5 with `blocked` status
+
+**Step 5: Return JSON Result**
+Return one of the following as the final response (see Output Format for schemas):
+- `status: "approved"` — all quality checks pass
+- `status: "blocked"` — specification unclear, business judgment required
 
 ## Status Determination Criteria (Binary Determination)
 
@@ -144,7 +149,6 @@ Apply fixes following the principles in coding-rules skill and testing skill.
     "totalWarnings": 0,
     "executionTime": "2m 15s"
   },
-  "approved": true,
   "nextActions": "Ready to commit"
 }
 ```
@@ -170,11 +174,9 @@ Apply fixes following the principles in coding-rules skill and testing skill.
 }
 ```
 
-### User Report (Mandatory)
-
-Summarize quality check results in an understandable way for users
+## Intermediate Progress Report
 
-### Phase-by-phase Report (Detailed Information)
+During execution, report progress between tool calls using this format:
 
 ```markdown
 Phase [Number]: [Phase Name]
@@ -192,6 +194,12 @@ Issues requiring fixes:
 Phase [Number] Complete! Proceeding to next phase.
 ```
 
+This is intermediate output only. The final response must be the JSON result (Step 5).
+
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `approved` or `blocked`
+
 ## Important Principles
 
 MUST follow these principles to maintain high-quality code:
@@ -221,7 +229,7 @@ MUST follow these principles to maintain high-quality code:
 
 **Required Fix Approaches**:
 - Test failures → Fix implementation or test logic to pass genuinely
-- Type errors → Add proper types or type guards with explicit typing
+- Type/contract errors → Fix type mismatches or interface/contract violations at their source
 - Errors → Log with context or propagate with error chain
 - Safety warnings → Address root cause directly
 

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

@@ -112,6 +112,9 @@ Identify constraints, risks, and dependencies. Use web search to verify current
 ### 6. Formulate Questions
 Identify any ambiguities that affect scale determination (scopeDependencies) or require user confirmation before proceeding.
 
+### 7. Return JSON Result
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 **JSON format is mandatory.**
@@ -161,6 +164,7 @@ Identify any ambiguities that affect scale determination (scopeDependencies) or
 - [ ] Have I correctly determined ADR necessity?
 - [ ] Have I not overlooked technical risks?
 - [ ] Have I listed scopeDependencies for uncertain scale?
+- [ ] Final response is the JSON output
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/rule-advisor.toml

@@ -65,6 +65,9 @@ From each skill:
 - Prioritize concrete procedures over abstract principles
 - Include checklists and actionable items
 
+### 4. Return JSON Result
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 Return structured JSON:
@@ -172,6 +175,12 @@ Return structured JSON:
 - MUST include enough context for standalone understanding
 - Prioritize actionable guidance over theory
 
+## Completion Criteria
+
+- [ ] Task analysis completed with type, scale, and tags
+- [ ] Relevant skills loaded and sections extracted
+- [ ] Final response is the JSON output
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

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

@@ -49,8 +49,8 @@ Skill Status:
 
 ## Output Scope
 
-This agent outputs **scope discovery results and evidence only**.
-Document generation is out of scope for this agent.
+This agent outputs **scope discovery results, evidence, and PRD unit grouping**.
+Document generation (PRD content, Design Doc content) is out of scope for this agent.
 
 ## Core Responsibilities
 
@@ -87,7 +87,7 @@ Explore the codebase from both user-value and technical perspectives simultaneou
 | Test Files | 2 | User-value | E2E tests, integration tests (often named by feature) |
 | User-facing Components | 3 | User-value | Pages, screens, major UI components |
 | Module Structure | 4 | Technical | Service classes, controllers, repositories |
-| Interface Definitions | 5 | Technical | Public APIs, exported functions, type definitions |
+| Public Interfaces | 5 | Technical | Public APIs, exported functions, data shapes/schemas |
 | Dependency Graph | 6 | Technical | Import/export relationships, DI configurations |
 | Directory Structure | 7 | Both | Feature-based directories, domain directories |
 | Data Flow | 8 | Technical | Data transformations, state management |
@@ -115,8 +115,10 @@ Explore the codebase from both user-value and technical perspectives simultaneou
    - Identify interface contracts
 
 4. **Synthesis into Functional Units**
-   - Merge user-value groups and technical boundaries into functional units
+   - Combine user-value groups and technical boundaries into functional units
    - Each unit MUST represent a coherent feature with identifiable technical scope
+   - For each unit, identify its `valueProfile`: who uses it, what goal it serves, and what high-level capability it belongs to
+   - Also assign normalized grouping keys in `valueProfile.groupingKey` for persona, goal, and category; use short stable slugs (`kebab-case`) rather than free-form prose
    - Apply Granularity Criteria (see below)
 
 5. **Boundary Validation**
@@ -128,6 +130,16 @@ Explore the codebase from both user-value and technical perspectives simultaneou
    - Stop discovery when 3 consecutive new sources yield no new units
    - Mark discovery as saturated in output
 
+7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete)
+   - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units
+   - Grouping logic: units with the same `groupingKey.valueCategory` AND the same `groupingKey.userGoal` AND the same `groupingKey.targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units
+   - Free-text fields (`targetPersona`, `userGoal`, `valueCategory`) are explanatory only and MUST NOT be used as grouping keys
+   - Every discovered unit must appear in exactly one PRD unit's `sourceUnits`
+   - Output as `prdUnits` alongside `discoveredUnits` (see Output Format)
+
+8. **Return JSON Result**
+   - Return the JSON result as the final response. See Output Format for the schema.
+
 ## Granularity Criteria
 
 Each discovered unit MUST represent a Vertical Slice — a coherent functional unit that spans all relevant layers — and satisfy:
@@ -138,11 +150,13 @@ Each discovered unit MUST represent a Vertical Slice — a coherent functional u
 - Multiple independent user journeys within one unit
 - Multiple distinct data domains with no shared state
 
-**Merge signals** (units may be too granular):
+**Cohesion signals** (units that may belong together):
 - Units share >50% of related files
 - One unit cannot function without the other
 - Combined scope is still under 10 files
 
+Note: These signals are informational only during steps 1-6. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 7 after discovery is complete, using normalized grouping keys rather than free-text descriptions.
+
 ## Confidence Assessment
 
 | Level | Triangulation Strength | Criteria |
@@ -174,6 +188,16 @@ Each discovered unit MUST represent a Vertical Slice — a coherent functional u
       "entryPoints": ["/path1", "/path2"],
       "relatedFiles": ["src/feature/*"],
       "dependencies": ["UNIT-002"],
+      "valueProfile": {
+        "targetPersona": "Who this feature serves (e.g., 'end user', 'admin', 'developer')",
+        "userGoal": "What the user is trying to accomplish with this feature",
+        "valueCategory": "High-level capability this belongs to (e.g., 'Authentication', 'Content Management', 'Reporting')",
+        "groupingKey": {
+          "targetPersona": "end-user",
+          "userGoal": "sign-in",
+          "valueCategory": "authentication"
+        }
+      },
       "technicalProfile": {
         "primaryModules": ["src/auth/service.ts", "src/auth/controller.ts"],
         "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
@@ -196,6 +220,21 @@ Each discovered unit MUST represent a Vertical Slice — a coherent functional u
       "suggestedAction": "What to do"
     }
   ],
+  "prdUnits": [
+    {
+      "id": "PRD-001",
+      "name": "PRD unit name (user-value level)",
+      "description": "What this capability delivers to the user",
+      "groupingKey": {
+        "targetPersona": "end-user",
+        "userGoal": "sign-in",
+        "valueCategory": "authentication"
+      },
+      "sourceUnits": ["UNIT-001", "UNIT-003"],
+      "combinedRelatedFiles": ["src/feature-a/*", "src/feature-b/*"],
+      "combinedEntryPoints": ["/path1", "/path2", "/path3"]
+    }
+  ],
   "limitations": ["What could not be discovered and why"]
 }
 ```
@@ -209,11 +248,14 @@ Each discovered unit MUST represent a Vertical Slice — a coherent functional u
 - [ ] Mapped public interfaces
 - [ ] Analyzed dependency graph
 - [ ] Applied granularity criteria (split/merge as needed)
+- [ ] Identified value profile (persona, goal, category) for each unit
 - [ ] Mapped discovered units to evidence sources
 - [ ] Assessed triangulation strength for each unit
 - [ ] Documented relationships between units
 - [ ] Reached saturation or documented why not
 - [ ] Listed uncertain areas and limitations
+- [ ] Grouped discovered units into PRD units (step 7, after all discovery steps complete)
+- [ ] Final response is the JSON output
 
 ## Output Self-Check
 - [ ] Output is limited to scope discovery (no PRD or Design Doc content generated)

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

@@ -101,6 +101,9 @@ Each finding must include a `rationale` field whose content depends on the categ
 | **hardening** | Why the current state is acceptable, and what improvement would add |
 | **policy** | Why this is not a technical vulnerability (what mitigates the technical risk) |
 
+### 6. Return JSON Result
+Return the JSON result as the final response. See Output Format for the schema.
+
 ## Output Format
 
 ```json
@@ -155,6 +158,7 @@ Each finding must include a `rationale` field whose content depends on the categ
 - [ ] Each finding classified into confirmed_risk / defense_gap / hardening / policy
 - [ ] False positives excluded considering runtime environment and existing mitigations
 - [ ] Committed secrets checked (blocked status if found)
+- [ ] Final response is the JSON output
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/solver.toml

@@ -111,12 +111,15 @@ Recommendation strategy based on confidence:
 - medium: Staged approach, verify with low-impact fixes before full implementation
 - low: Start with conservative mitigation, prioritize solutions that address multiple possible causes
 
-### Step 5: Implementation Steps Creation and Output
+### Step 5: Implementation Steps Creation
 - Each step independently verifiable
 - Explicitly state dependencies between steps
 - Define completion conditions for each step
 - Include rollback procedures
-- Output structured report in JSON format
+
+### Step 6: Return JSON Result
+
+Return the JSON result as the final response. See Output Format for the schema.
 
 ## Output Format
 
@@ -184,6 +187,7 @@ Recommendation strategy based on confidence:
 - [ ] Documented residual risks
 - [ ] Verified solutions align with project rules or best practices
 - [ ] Verified input consistency with user report
+- [ ] Final response is the JSON output
 
 ## Output Self-Check
 - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion)

package/.codex/agents/task-executor-frontend.toml

@@ -184,6 +184,11 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 Task complete when all checkbox items completed and operation verification complete.
 For research tasks, includes creating deliverable files specified in metadata "Provides" section.
 
+### 5. Return JSON Result
+Return one of the following as the final response (see Structured Response Specification for schemas):
+- `status: "completed"` — task fully implemented
+- `status: "escalation_needed"` — design deviation or similar component discovered
+
 ## Research Task Deliverables
 
 Research/analysis tasks create deliverable files specified in metadata "Provides".
@@ -291,6 +296,10 @@ When discovering similar components/hooks during existing code investigation, es
 - Design Doc deviation → escalate to orchestrator immediately
 - Component patterns → use functional components exclusively (React standard)
 
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

package/.codex/agents/task-executor.toml

@@ -185,6 +185,11 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 Task complete when all checkbox items completed and operation verification complete.
 For research tasks, includes creating deliverable files specified in metadata "Provides" section.
 
+### 5. Return JSON Result
+Return one of the following as the final response (see Structured Response Specification for schemas):
+- `status: "completed"` — task fully implemented
+- `status: "escalation_needed"` — design deviation or similar function discovered
+
 ## Research Task Deliverables
 
 Research/analysis tasks create deliverable files specified in metadata "Provides".
@@ -293,6 +298,10 @@ When discovering similar functions during existing code investigation, escalate
 - Escalate when: design deviation, similar functions found, test environment missing
 - Stop after implementation and test creation — quality checks and commits are handled separately
 
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

package/.codex/agents/verifier.toml

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

package/README.md

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

package/package.json

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