codex-workflows 0.4.9 → 0.4.11

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

@@ -9,6 +9,8 @@ description: "Add integration/E2E tests to existing codebase using Design Docs."
 2. [LOAD IF NOT ACTIVE] `integration-e2e-testing` — integration and E2E test patterns
 3. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Test addition workflow for existing implementations
 
 ## Orchestrator Definition

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

@@ -10,6 +10,8 @@ description: "Execute decomposed backend tasks in autonomous execution mode usin
 3. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
 4. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)

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

@@ -9,6 +9,8 @@ description: "Execute from requirement analysis to design document creation."
 2. [LOAD IF NOT ACTIVE] `implementation-approach` — implementation strategy
 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Dedicated to the design phase.
 
 ## Orchestrator Definition

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

@@ -8,6 +8,8 @@ description: "Investigate problem, verify findings, and derive solutions through
 1. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
 2. [LOAD IF NOT ACTIVE] `coding-rules` — coding standards
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Diagnosis flow to identify concrete failure points and present solutions
 
 Target problem: $ARGUMENTS

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

@@ -10,6 +10,8 @@ description: "Execute frontend tasks in autonomous execution mode using task-exe
 3. [LOAD IF NOT ACTIVE] `ai-development-guide` -- AI development patterns
 4. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)

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

@@ -11,6 +11,8 @@ description: "Execute from requirement analysis to frontend design document crea
 2. [LOAD IF NOT ACTIVE] `implementation-approach` -- implementation methodology
 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator."

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

@@ -11,6 +11,8 @@ description: "Create frontend work plan from design document with test skeleton
 2. [LOAD IF NOT ACTIVE] `implementation-approach` -- implementation methodology
 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator."

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

@@ -11,6 +11,8 @@ description: "Frontend Design Doc compliance and security validation with option
 2. [LOAD IF NOT ACTIVE] `testing` -- test strategy and quality gates
 3. [LOAD IF NOT ACTIVE] `ai-development-guide` -- AI development patterns
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Execution Method
 
 - Compliance validation -> performed by code-reviewer

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

@@ -10,6 +10,8 @@ description: "Execute decomposed fullstack tasks with layer-aware agent routing
 3. [LOAD IF NOT ACTIVE] `ai-development-guide` -- AI development patterns
 4. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)

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

@@ -14,6 +14,8 @@ description: "Orchestrate full-cycle implementation across backend and frontend
 5. [LOAD IF NOT ACTIVE] `implementation-approach` -- implementation methodology
 6. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Orchestrator Definition
 
 **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)

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

@@ -8,6 +8,8 @@ description: "Orchestrate the complete implementation lifecycle from requirement
 1. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 2. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 # Full-Cycle Implementation
 
 $ARGUMENTS

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

@@ -9,6 +9,8 @@ description: "Create work plan from design document with optional test skeleton
 2. [LOAD IF NOT ACTIVE] `implementation-approach` — implementation strategy
 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Dedicated to the planning phase.
 
 ## Orchestrator Definition

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

@@ -9,6 +9,8 @@ description: "Generate PRD and Design Docs from existing codebase through discov
 2. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Reverse engineering workflow to create documentation from existing code
 
 Target: $ARGUMENTS

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

@@ -9,6 +9,8 @@ description: "Design Doc compliance and security validation with optional auto-f
 2. [LOAD IF NOT ACTIVE] `testing` — test strategy and quality gates
 3. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Post-implementation quality assurance
 
 ## Orchestrator Definition

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

@@ -7,6 +7,8 @@ description: "Execute tasks with metacognitive analysis and appropriate rule sel
 
 1. [LOAD IF NOT ACTIVE] `task-analyzer` — task analysis and skill selection (rule-advisor handles remaining skill selection)
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 # Task Execution with Metacognitive Analysis
 
 Task: $ARGUMENTS

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

@@ -8,6 +8,8 @@ description: "Update existing design documents (Design Doc / PRD / ADR) with rev
 1. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
 2. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 **Context**: Dedicated to updating existing design documents.
 
 ## Orchestrator Definition

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

@@ -5,6 +5,8 @@ description: "Guides subagent coordination through implementation workflows. Use
 
 # Subagents Orchestration Guide
 
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
 ## Role: The Orchestrator
 
 The orchestrator coordinates subagents. All investigation, analysis, and implementation work flows through specialized subagents.
@@ -96,28 +98,51 @@ Subagents CANNOT directly call other subagents — all coordination MUST flow th
 
 **ENFORCEMENT**: Direct subagent-to-subagent communication is PROHIBITED
 
+### Subagent Completion Discipline [MANDATORY]
+
+The orchestrator owns subagent completion. Base waiting decisions on assigned responsibility and observed state, not on an expectation of quick completion. Multi-step search, review, verification, generation, implementation, and quality work can run for extended periods.
+
+Use this contract:
+- Wait for required subagent outputs with `wait_agent`
+- Keep the current task assignment while the subagent remains `running`
+- Treat missing intermediate output as a normal execution state while the subagent remains `running`
+- Hold final artifact production until every required subagent output is available
+- After repeated empty waits, run non-destructive diagnostics: re-check prompt, inputs, expected deliverable, and agent-task fit; send a focused follow-up when it would clarify the pending deliverable
+- Resume waiting after diagnostics unless the user redirects the workflow or the orchestrator confirms a launch mistake
+
+Treat the following as explicit contradictory evidence:
+- The subagent returns a terminal status such as `approved`, `needs_revision`, `blocked`, `skipped`, `completed`, or `escalation_needed`
+- The orchestrator verifies that it launched the wrong subagent or sent materially incorrect inputs
+- A newer explicit user instruction changes or cancels the task
+
+Close a running subagent only when the user redirects the workflow, the orchestrator corrects a launch mistake, or a newer user instruction supersedes the pending task.
+
+**ENFORCEMENT**: Preserve subagent execution until completion, user redirection, or explicit correction of an orchestrator launch mistake. Speed-based early termination is a CRITICAL VIOLATION.
+
 ## How to Spawn Agents
 
-Spawn agents using natural language prompts. Provide clear context about what the agent should accomplish.
+Spawn agents using natural language prompts. Provide clear context about what the agent should accomplish. Every `spawn_agent` call MUST include `fork_turns="none"` or `fork_context=false` (see Spawn rule at top of this skill).
 
 ### Spawn Examples
 
-**requirement-analyzer**:
+Each example below is a spawn with `fork_turns="none"` or `fork_context=false` plus the quoted prompt.
+
+**requirement-analyzer** (`fork_turns="none"` or `fork_context=false`):
 > "Analyze the following requirements and determine the work scale: [user requirements]. Perform requirement analysis and scale determination."
 
-**codebase-analyzer**:
+**codebase-analyzer** (`fork_turns="none"` or `fork_context=false`):
 > "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**:
+**task-executor** (`fork_turns="none"` or `fork_context=false`):
 > "Execute the implementation task defined in docs/plans/tasks/[filename].md. Complete the implementation following TDD Red-Green-Refactor."
 
-**quality-fixer**:
+**quality-fixer** (`fork_turns="none"` or `fork_context=false`):
 > "Run quality checks on the codebase: static analysis, style check, all test execution. Fix any issues found and report when all checks pass."
 
-**document-reviewer**:
+**document-reviewer** (`fork_turns="none"` or `fork_context=false`):
 > "Review the document at [path] for quality and rule compliance. Check against documentation-criteria standards."
 
-**design-sync**:
+**design-sync** (`fork_turns="none"` or `fork_context=false`):
 > "Verify consistency between Design Docs in docs/design/. Use [path] as the source document for comparison."
 
 ## Explicit Stop Points [MANDATORY]
@@ -149,16 +174,9 @@ All agents MUST use this vocabulary consistently:
 | `blocked` | security-reviewer | Committed secrets or high-confidence exploitable risk | Halt workflow immediately, escalate to user (requires human intervention) |
 | `skipped` | All agents | Preconditions not met for this step | Report reason, proceed |
 
-**approved_with_conditions handling** (document agents):
-- Conditions MUST be listed explicitly in the agent's output
-- Orchestrator MUST append conditions to the document's "Undetermined Items" or "Open Items" section before proceeding
-- Orchestrator MUST pass conditions to the next phase's agent as context
-- Conditions do not block progression but MUST be resolved before implementation phase
-
-**approved_with_notes handling** (security-reviewer):
-- Notes are informational — they do NOT require resolution before proceeding
-- Orchestrator MUST include notes in the completion report for awareness
-- Do not apply approved_with_conditions handling (no resolution tracking)
+Handling rules:
+- `approved_with_conditions`: append the listed conditions to the document's open-items section, carry them into the next phase, and resolve them before implementation
+- `approved_with_notes`: include the notes in the completion report for awareness
 
 **ENFORCEMENT**: Using any status value outside this vocabulary is a VIOLATION.
 
@@ -176,17 +194,20 @@ All agents MUST use this vocabulary consistently:
 
 ## Structured Response Specification
 
-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, qualityAssurance, 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/dependency_version_uncertain), testsAdded, requiresTestReview
-- **quality-fixer**: Input: `task_file` (always pass the current task file path in orchestrated flows). Status (`stub_detected`/approved/blocked). `stub_detected` returns `stubFindings[]` and routes back to the task executor. 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.status, summary.consistencyScore, 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
-- **acceptance-test-generator**: status, generatedFiles, `e2eAbsenceReason`
+Subagents respond in JSON format. The final response from each JSON-returning subagent must be the JSON payload itself, with no trailing prose. Agent TOML files define the full schemas; the orchestrator only relies on these routing keys:
+
+| Agent | Routing fields the orchestrator uses |
+|-------|--------------------------------------|
+| `requirement-analyzer` | `scale`, `confidence`, `affectedLayers`, `adrRequired`, `scopeDependencies`, `questions` |
+| `codebase-analyzer` | `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
+| `task-executor*` | `status`, `escalation_type`, `filesModified`, `requiresTestReview` |
+| `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
+| `document-reviewer` | `verdict.decision`, `verdict.conditions` |
+| `code-verifier` | `summary.status`, `discrepancies`, `reverseCoverage` |
+| `design-sync` | `sync_status` |
+| `integration-test-reviewer` | `status`, `requiredFixes` |
+| `security-reviewer` | `status`, `findings`, `notes`, `requiredFixes` |
+| `acceptance-test-generator` | `status`, `generatedFiles`, `e2eAbsenceReason` |
 
 ## Handling Requirement Changes
 
@@ -215,51 +236,21 @@ Document generation agents (work-planner, technical-designer, prd-creator) can u
 
 ## Basic Flow for Work Planning
 
-When receiving new features or change requests, start with requirement-analyzer.
-
-### 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
-3. document-reviewer: PRD review **[Stop: PRD Approval]**
-4. **(frontend/fullstack only)** Ask user for prototype code; ui-spec-designer: UI Spec creation
-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. 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) - 9 Steps (backend) / 11 Steps (frontend/fullstack)
-
-1. requirement-analyzer: Requirement analysis **[Stop]**
-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`, including `dataTransformationPipelines` and `qualityAssurance` when present
-- Pass Design Doc path to code-verifier
-- Pass code-verifier JSON to document-reviewer as `code_verification`
-
-### Small Scale (1-2 Files) - 2 Steps
-
-1. Create simplified plan **[Stop: Batch approval]**
-2. Direct implementation to Completion report
+Always start with `requirement-analyzer`, then follow the minimum flow required by scale and affected layers.
+
+| Scale | Required flow |
+|-------|---------------|
+| Large | `requirement-analyzer` **[Stop]** -> `prd-creator` -> `document-reviewer` **[Stop]** -> optional `ui-spec-designer` + `document-reviewer` **[Stop]** -> optional ADR + `document-reviewer` **[Stop]** -> `codebase-analyzer` -> `technical-designer*` -> `code-verifier` -> `document-reviewer` -> `design-sync` **[Stop]** -> `acceptance-test-generator` -> `work-planner` **[Stop]** -> `task-decomposer` |
+| Medium | `requirement-analyzer` **[Stop]** -> `codebase-analyzer` -> optional `ui-spec-designer` + `document-reviewer` **[Stop]** -> `technical-designer*` -> `code-verifier` -> `document-reviewer` -> `design-sync` **[Stop]** -> `acceptance-test-generator` -> `work-planner` **[Stop]** -> `task-decomposer` |
+| Small | `requirement-analyzer` **[Stop]** -> simplified plan **[Stop: Batch approval]** -> direct implementation |
+
+Flow rules:
+- Frontend and fullstack flows add UI Spec before Design Doc creation
+- Create ADR only when architecture, technology, or data-flow changes require it
+- Pass requirement-analyzer output and original requirements to `codebase-analyzer`
+- Pass `codebase-analyzer` output to the designer as `Codebase Analysis`
+- Pass Design Doc path to `code-verifier`, then pass `code_verification` to `document-reviewer`
+- Fullstack layer sequencing is defined in `references/monorepo-flow.md`
 
 ## Autonomous Execution Mode
 
@@ -316,6 +307,13 @@ 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
 
+Continue autonomous execution in the following situations:
+- A subagent takes longer than expected
+- `wait_agent` returns without a completion payload while the subagent remains `running`
+- The orchestrator has partial context but is still waiting on a required subagent output
+
+If repeated waits return the same `running` state, apply the completion-diagnostics contract above.
+
 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
@@ -338,49 +336,27 @@ Maximum retry count is 1 verification fix cycle. If any failed verifier still fa
 2. **Information Bridging**: Data conversion and transmission between subagents
    - Convert each subagent's output to next subagent's input format
    - **Always pass deliverables from previous process to next agent**
-   - Extract necessary information from structured responses
-   - Compose commit messages from changeSummary
+   - Extract the routing fields listed above
    - Explicitly integrate initial and additional requirements when requirements change
 3. **Quality Assurance and Commit Execution**: Execute git commit per the 4-step task cycle
 4. **Autonomous Execution Mode Management**: Start/stop autonomous execution after approval, escalation decisions
 5. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected)
 
-### acceptance-test-generator to work-planner Bridge
-
-**Pass to acceptance-test-generator**:
-- Design Doc: [path]
-- UI Spec: [path] (if exists)
-
-**Orchestrator verification items**:
-- Verify integration test file path retrieval and existence
-- Verify E2E test file path retrieval and existence when `generatedFiles.e2e` is not null
-- Verify `e2eAbsenceReason` is present when `generatedFiles.e2e` is null
-
-**Pass to work-planner**:
-- Integration test file: [path] (create and execute simultaneously with each phase implementation)
-- E2E test file: [path] or `null` (execute only in final phase when present)
-- E2E absence reason: [value when E2E test file is null]
-
-**On error**: Escalate to user only when required outputs are missing without a valid absence reason
-
-### 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.
-When the Design Doc includes an `Output Comparison` section, carry forward the comparison input, expected output fields or format, diff method, and transformation pipeline coverage as part of that summary.
-
-In addition, the orchestrator must preserve implementation-relevant technical requirements from each Design Doc so work-planner can create a Design-to-Plan Traceability table. Use the category values and normalization rules defined in the plan template, including protected no-change boundaries from sections such as `No Ripple Effect`.
-
-Work-planner maps each extracted item to a covering task or phase. If no covering task exists, the row is marked `gap` with justification. Justified gaps require user confirmation before plan approval.
+### Required Handoffs
+
+| From | To | Required pass-through |
+|------|----|-----------------------|
+| `requirement-analyzer` | `codebase-analyzer` | requirement analysis JSON, original requirements, PRD path when available |
+| `codebase-analyzer` | `technical-designer*` | `Codebase Analysis`, including `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
+| `technical-designer*` | `code-verifier` | Design Doc path |
+| `code-verifier` | `document-reviewer` | `code_verification` JSON |
+| `acceptance-test-generator` | `work-planner` | integration test path, E2E path or `null`, `e2eAbsenceReason` when E2E is absent |
+| Design Doc | `work-planner` | Verification Strategy summary, Output Comparison details, implementation-relevant technical requirements, protected no-change boundaries |
+
+Handoff rules:
+- Verify generated integration and E2E file paths exist before passing them onward
+- Escalate only when required outputs are missing without a valid absence reason
+- Require work-planner to map every carried-forward technical requirement to a covering task or a justified `gap`
 
 ## Important Constraints [MANDATORY]
 

package/README.md

@@ -363,9 +363,9 @@ A: `$recipe-implement` is the universal entry point. It runs requirement-analyze
 
 A: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.
 
-**Q: What if a subagent gets stuck?**
+**Q: What if a subagent seems stuck?**
 
-A: Subagents escalate to the user when they encounter design deviations, ambiguous requirements, or specification conflicts. The framework stops autonomous execution and presents the issue with options.
+A: Long waits can be normal in this workflow because many subagents perform substantial multi-step work. The orchestrator keeps ownership of the pending deliverable, continues waiting for the required output, and uses diagnostics only to confirm missing inputs or restate the pending deliverable. User direction remains the boundary for interrupting that work.
 
 ---
 

package/package.json

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