codex-workflows 0.1.0

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

@@ -0,0 +1,73 @@
+---
+name: recipe-plan
+description: "Create work plan from design document with optional test skeleton generation."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
+2. [LOAD IF NOT ACTIVE] `implementation-approach` — implementation strategy
+3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
+
+**Context**: Dedicated to the planning phase.
+
+## Orchestrator Definition
+
+**Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)
+
+**Execution Protocol**:
+1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
+2. **Follow subagents-orchestration-guide skill planning flow exactly**:
+   - Execute steps defined below
+   - **[STOP — BLOCKING]** Present plan content to user for approval. **CANNOT proceed until user explicitly confirms.**
+3. **Scope**: Complete when work plan receives approval
+
+**CRITICAL**: When the user requests test generation, MUST spawn acceptance-test-generator agent first -- it provides the test skeleton that work-planner depends on.
+ENFORCEMENT: Work-planner spawned without test skeleton data (when tests were requested) produces incomplete plans.
+
+## Scope Boundaries
+
+**Included in this skill**:
+- Design document selection
+- Test skeleton generation with acceptance-test-generator
+- Work plan creation with work-planner
+- Plan approval obtainment
+
+**Responsibility Boundary**: This skill completes with work plan approval.
+
+Follow the planning process below:
+
+## Execution Process
+
+### Step 1: Design Document Selection
+Check for existence of design documents in docs/design/, notify user if none exist.
+Present options if multiple exist (can be specified with $ARGUMENTS).
+
+### Step 2: E2E Test Skeleton Generation Confirmation
+- Confirm with user whether to generate E2E test skeleton first
+- If user wants generation: Spawn acceptance-test-generator agent: "Generate test skeletons from Design Doc at [design-doc-path]"
+- Pass generation results to next process according to subagents-orchestration-guide skill coordination specification
+
+### Step 3: Work Plan Creation
+- Spawn work-planner agent: "Create work plan from design document at [design-doc-path]. Include deliverables from previous process according to subagents-orchestration-guide skill coordination specification."
+- Interact with user to complete plan and obtain approval for plan content
+- Clarify specific implementation steps and risks
+
+**Scope**: Up to work plan creation and obtaining approval for plan content.
+
+## Completion Criteria
+
+- [ ] Design document identified and selected
+- [ ] E2E test skeleton generation confirmed with user (generated if requested)
+- [ ] Work plan created via work-planner
+- [ ] Plan content approved by user
+- [ ] All stopping points honored with user confirmation
+
+## Response at Completion
+```
+Planning phase completed.
+- Work plan: docs/plans/[plan-name].md
+- Status: Approved
+
+Please provide separate instructions for implementation.
+```

package/.agents/skills/recipe-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-plan"
+  short_description: "Design document to work plan creation"
+  default_prompt: "Use $recipe-plan to start planning: "
+
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,212 @@
+---
+name: recipe-reverse-engineer
+description: "Generate PRD and Design Docs from existing codebase through discovery, generation, verification, and review."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
+2. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
+3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
+
+**Context**: Reverse engineering workflow to create documentation from existing code
+
+Target: $ARGUMENTS
+
+## Orchestrator Definition
+
+**Core Identity**: "I am not a worker. I am an orchestrator."
+
+**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
+
+**Task Registration**: Register phases first, then steps within each phase as you enter it. Track status for each step.
+
+## Step 0: Initial Configuration
+
+### 0.1 Scope Confirmation
+
+Ask the user to confirm:
+1. **Target path**: Which directory/module to document
+2. **Depth**: PRD only, or PRD + Design Docs
+3. **Reference Architecture**: layered / mvc / clean / hexagonal / none
+4. **Human review**: Yes (recommended) / No (fully autonomous)
+
+### 0.2 Output Configuration
+
+- PRD output: `docs/prd/` or existing PRD directory
+- Design Doc output: `docs/design/` or existing design directory
+- Verify directories exist, create if needed
+
+## Workflow Overview
+
+```
+Phase 1: PRD Generation
+  Step 1: Scope Discovery (unified, single pass)
+  Step 2-5: Per-unit loop (Generation -> Verification -> Review -> Revision)
+
+Phase 2: Design Doc Generation (if requested)
+  Step 6: Design Doc Scope Mapping (reuse Step 1 results, no re-discovery)
+  Step 7-10: Per-unit loop (Generation -> Verification -> Review -> Revision)
+```
+
+## Phase 1: PRD Generation
+
+**Register tasks**:
+- Step 1: PRD Scope Discovery
+- Per-unit processing (Steps 2-5 for each unit)
+
+### Step 1: PRD Scope Discovery
+
+Spawn scope-discoverer agent: "Discover functional scope targets in the codebase. target_path: $USER_TARGET_PATH. reference_architecture: $USER_RA_CHOICE. focus_area: $USER_FOCUS_AREA (if specified)."
+
+**Store output as**: `$STEP_1_OUTPUT`
+
+**Quality Gate**:
+- At least one unit discovered -> proceed
+- No units discovered -> ask user for hints
+
+**[STOP — BLOCKING]** If human review enabled: Present discovered units 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)**:
+
+#### 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."
+
+**Store output as**: `$STEP_2_OUTPUT` (PRD path)
+
+#### Step 3: Code Verification
+
+**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."
+
+**Store output as**: `$STEP_3_OUTPUT`
+
+**Quality Gate**:
+- consistencyScore >= 70 -> proceed to review
+- consistencyScore < 70 -> flag for detailed review
+
+#### Step 4: Review
+
+**Required Input**: $STEP_3_OUTPUT (verification data from Step 3)
+
+Spawn document-reviewer agent: "Review the following PRD considering code verification findings. doc_type: PRD. target: $STEP_2_OUTPUT. mode: composite. Code Verification Results: $STEP_3_OUTPUT. Additional Review Focus: Alignment between PRD claims and verification evidence, resolution recommendations for each discrepancy, completeness of undocumented feature coverage."
+
+**Store output as**: `$STEP_4_OUTPUT`
+
+#### Step 5: Revision (conditional)
+
+**Trigger Conditions** (any one of the following):
+- Review status is "Needs Revision" or "Rejected"
+- Critical discrepancies exist in `$STEP_3_OUTPUT`
+- consistencyScore < 70
+
+Spawn prd-creator agent: "Update PRD based on review feedback and code verification results. Operation Mode: update. Existing PRD: $STEP_2_OUTPUT. Review Feedback: $STEP_4_OUTPUT. Code Verification Results: $STEP_3_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale."
+
+**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status.
+ENFORCEMENT: Exceeding 2 revision cycles without flagging produces unreviewed output.
+
+#### Unit Completion
+
+- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] Human review passed (if enabled in Step 0)
+
+**Next**: Proceed to next unit. After all units -> Phase 2.
+
+## Phase 2: Design Doc Generation
+
+*Execute only if Design Docs were requested in Step 0*
+
+**Register tasks**:
+- Step 6: Design Doc Scope Mapping
+- Per-unit processing (Steps 7-10 for each unit)
+
+### Step 6: Design Doc Scope Mapping
+
+**No additional discovery required.** Use `$STEP_1_OUTPUT` (scope discovery results) directly.
+
+Each PRD unit from Phase 1 maps to one Design Doc unit (using technical-designer).
+
+Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward:
+- `technicalProfile.primaryModules` -> Primary Files
+- `technicalProfile.publicInterfaces` -> Public Interfaces
+- `dependencies` -> Dependencies
+- `relatedFiles` -> Scope boundary
+
+**Store output as**: `$STEP_6_OUTPUT`
+
+### Step 7-10: Per-Unit Processing
+
+**FOR** each unit in `$STEP_6_OUTPUT` **(sequential, one unit at a time)**:
+
+#### Step 7: Design Doc Generation
+
+**Scope**: Document current architecture as-is. This is a documentation task, not a design improvement task.
+
+Spawn technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: create. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Primary Files: $UNIT_PRIMARY_MODULES. Public Interfaces: $UNIT_PUBLIC_INTERFACES. Dependencies: $UNIT_DEPENDENCIES. Parent PRD: $APPROVED_PRD_PATH. Document current architecture as-is."
+
+**Store output as**: `$STEP_7_OUTPUT`
+
+#### Step 8: Code Verification
+
+Spawn code-verifier agent: "Verify consistency between Design Doc and code implementation. doc_type: design-doc. document_path: $STEP_7_OUTPUT. code_paths: $UNIT_PRIMARY_MODULES. verbose: false."
+
+**Store output as**: `$STEP_8_OUTPUT`
+
+#### Step 9: Review
+
+**Required Input**: $STEP_8_OUTPUT (verification data from Step 8)
+
+Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doc_type: DesignDoc. target: $STEP_7_OUTPUT. mode: composite. Code Verification Results: $STEP_8_OUTPUT. Parent PRD: $APPROVED_PRD_PATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions."
+
+**Store output as**: `$STEP_9_OUTPUT`
+
+#### Step 10: Revision (conditional)
+
+**Trigger Conditions** (same as Step 5):
+- Review status is "Needs Revision" or "Rejected"
+- Critical discrepancies exist in `$STEP_8_OUTPUT`
+- consistencyScore < 70
+
+Spawn technical-designer agent: "Update Design Doc based on review feedback and code verification results. Operation Mode: update. Existing Design Doc: $STEP_7_OUTPUT. Review Feedback: $STEP_9_OUTPUT. Code Verification Results: $STEP_8_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale."
+
+**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status.
+
+#### Unit Completion
+
+- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] Human review passed (if enabled in Step 0)
+
+**Next**: Proceed to next unit. After all units -> Final Report.
+
+## Final Report
+
+Output summary including:
+- Generated documents table (Type, Name, Consistency Score, Review Status)
+- Action items (critical discrepancies, undocumented features, flagged items)
+- Next steps checklist
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Discovery finds nothing | Ask user for project structure hints |
+| Generation fails | Log failure, continue with other units, report in summary |
+| consistencyScore < 50 | **[STOP — BLOCKING]** Flag for mandatory human review. **CANNOT proceed until user explicitly confirms.** |
+| Review rejects after 2 revisions | Stop loop, flag for human intervention |
+
+## Completion Criteria
+
+- [ ] Scope confirmed with user (target path, depth, architecture, human review preference)
+- [ ] Output directories verified/created
+- [ ] Phase 1: All PRD units discovered and processed (generation -> verification -> review -> revision)
+- [ ] Phase 2: All Design Doc units processed (if requested)
+- [ ] All human review points honored (if enabled)
+- [ ] Final report presented with document table, action items, and next steps

package/.agents/skills/recipe-reverse-engineer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-reverse-engineer"
+  short_description: "Generate documentation from existing codebase"
+  default_prompt: "Use $recipe-reverse-engineer to document: "
+
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,115 @@
+---
+name: recipe-review
+description: "Design Doc compliance validation with optional auto-fixes."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `coding-rules` — coding standards
+2. [LOAD IF NOT ACTIVE] `testing` — test strategy and quality gates
+3. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns
+
+**Context**: Post-implementation quality assurance
+
+## Orchestrator Definition
+
+**Core Identity**: "I am not a worker. I am an orchestrator."
+
+**First Action**: Register Steps 1-9 before any execution.
+
+## Execution Method
+
+- Compliance validation -> Spawn code-reviewer agent
+- Fix implementation -> Spawn task-executor agent
+- Quality checks -> Spawn quality-fixer agent
+- Re-validation -> Spawn code-reviewer agent
+
+Orchestrator spawns sub-agents and passes structured data between them.
+
+Design Doc (uses most recent if omitted): $ARGUMENTS
+
+## Execution Flow
+
+### Step 1: Prerequisite Check
+Identify Design Doc in docs/design/ and check implementation files via git diff.
+
+### Step 2: Execute code-reviewer
+Spawn code-reviewer agent: "Validate Design Doc compliance for the implementation. Check acceptance criteria fulfillment, code quality, and implementation completeness. Design Doc path: [path]"
+
+**Store output as**: `$STEP_2_OUTPUT`
+
+### Step 3: Verdict and Response
+
+**Criteria (considering project stage)**:
+- Prototype: Pass at 70%+
+- Production: 90%+ REQUIRED
+- Critical items (security, etc.): REQUIRED regardless of rate
+
+**Compliance-based response**:
+
+For low compliance (production <90%):
+```
+Validation Result: [X]% compliance
+Unfulfilled items:
+- [item list]
+
+Execute fixes? (y/n):
+```
+
+**[STOP — BLOCKING]** Present compliance results to user for confirmation.
+**CANNOT proceed until user explicitly confirms.**
+
+### Step 4: Prepare Fix Context
+
+If user selects `n` or compliance sufficient: Skip Steps 4-8, proceed to Step 9.
+
+Reference documentation-criteria skill for task file template.
+
+### Step 5: Create Task File
+
+Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md`
+
+### Step 6: Execute Fixes
+
+Spawn task-executor agent: "Execute review fixes. Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)."
+
+### Step 7: Quality Check
+
+Spawn quality-fixer agent: "Confirm quality gate passage for fixed files."
+
+### Step 8: Re-validate
+
+Spawn code-reviewer agent: "Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved."
+
+### Step 9: Final Report
+
+```
+Initial compliance: [X]%
+Final compliance: [Y]% (if fixes executed)
+Improvement: [Y-X]%
+
+Remaining issues:
+- [items requiring manual intervention]
+```
+
+## Auto-fixable Items
+- Simple unimplemented acceptance criteria
+- Error handling additions
+- Contract definition fixes
+- Function splitting (length/complexity improvements)
+
+## Non-fixable Items
+- Fundamental business logic changes
+- Architecture-level modifications
+- Design Doc deficiencies
+
+## Completion Criteria
+
+- [ ] Design Doc identified and implementation files checked
+- [ ] code-reviewer spawned and compliance validated
+- [ ] Compliance results presented to user
+- [ ] Fixes executed if user approved (with quality-fixer gate)
+- [ ] Re-validation completed after fixes
+- [ ] Final report presented to user
+
+**Scope**: Design Doc compliance validation and auto-fixes.

package/.agents/skills/recipe-review/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-review"
+  short_description: "Design Doc compliance validation with auto-fixes"
+  default_prompt: "Use $recipe-review to validate: "
+
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,74 @@
+---
+name: recipe-task
+description: "Execute tasks with metacognitive analysis and appropriate rule selection."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `task-analyzer` — task analysis and skill selection (rule-advisor handles remaining skill selection)
+
+# Task Execution with Metacognitive Analysis
+
+Task: $ARGUMENTS
+
+## Mandatory Execution Process
+
+**Step 1: Rule Selection via rule-advisor (REQUIRED)**
+
+Spawn rule-advisor agent: "Analyze the task and select appropriate rules for: $ARGUMENTS. Provide context about current situation and prerequisites."
+
+ENFORCEMENT: Skipping rule-advisor produces unguided execution with high failure risk.
+
+**Step 2: Utilize rule-advisor Output**
+
+After receiving rule-advisor's response, proceed with:
+
+1. **Understand Task Essence** (from `metaCognitiveGuidance.taskEssence`)
+   - Focus on fundamental purpose, not surface-level work
+   - Distinguish between "quick fix" vs "proper solution"
+
+2. **Follow Selected Rules** (from `selectedRules`)
+   - Review each selected rule section
+   - Apply concrete procedures and guidelines
+
+3. **Recognize Past Failures** (from `metaCognitiveGuidance.pastFailures`)
+   - Apply countermeasures for known failure patterns
+   - Use suggested alternative approaches
+
+4. **Execute First Action** (from `metaCognitiveGuidance.firstStep`)
+   - Start with recommended action and rationale
+   - Use suggested tools first
+
+**Step 3: Create Task List**
+
+Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity".
+
+Break down the task based on rule-advisor's guidance:
+- Reflect `metaCognitiveGuidance.taskEssence` in task descriptions
+- Apply `metaCognitiveGuidance.firstStep` to first task
+- Restructure tasks considering `warningPatterns`
+- Set appropriate priorities
+
+**Step 4: Execute Implementation**
+
+Proceed with task execution following:
+- Selected rules from rule-advisor
+- Task structure
+- Quality standards from applicable rules
+
+## Important Notes
+
+- **Spawn rule-advisor first**: MUST complete metacognitive step before implementation
+- **Update tasks after rule-advisor**: MUST reflect insights in task structure
+- **Follow metaCognitiveGuidance.firstStep**: MUST start with the recommended action
+- **Monitor warningPatterns**: MUST watch for failure patterns throughout execution
+
+## Completion Criteria
+
+- [ ] rule-advisor spawned and output received
+- [ ] Task essence understood from `metaCognitiveGuidance.taskEssence`
+- [ ] Selected rules reviewed and applied
+- [ ] Past failure patterns recognized and countermeasures applied
+- [ ] Task list created with skill constraint confirmation and fidelity verification
+- [ ] Implementation executed following rule-advisor guidance
+- [ ] Warning patterns monitored throughout execution

package/.agents/skills/recipe-task/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-task"
+  short_description: "Metacognitive task execution with rule selection"
+  default_prompt: "Use $recipe-task to execute: "
+
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,156 @@
+---
+name: recipe-update-doc
+description: "Update existing design documents (Design Doc / PRD / ADR) with review and consistency verification."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+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
+
+**Context**: Dedicated to updating existing design documents.
+
+## Orchestrator Definition
+
+**Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)
+
+**First Action**: Register Steps 1-6 before any execution.
+
+**Execution Protocol**:
+1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
+2. **Execute update flow**:
+   - Identify target -> Clarify changes -> Update document -> Review -> Consistency check
+   - **[STOP — BLOCKING]** At every `[Stop: ...]` marker -> Present status to user for confirmation. **CANNOT proceed until user explicitly confirms.**
+3. **Scope**: Complete when updated document receives approval
+
+**CRITICAL**: MUST execute document-reviewer and all stopping points -- each serves as a quality gate for document accuracy.
+ENFORCEMENT: Skipping document-reviewer risks propagating inconsistencies to downstream workflows.
+
+## Workflow Overview
+
+```
+Target document -> [Stop: Confirm changes]
+                        |
+              technical-designer / prd-creator (update mode)
+                        |
+              document-reviewer -> [Stop: Review approval]
+                        | (Design Doc only)
+              design-sync -> [Stop: Final approval]
+```
+
+## Scope Boundaries
+
+**Included in this skill**:
+- Existing document identification and selection
+- Change content clarification with user
+- Document update with appropriate agent (update mode)
+- Document review with document-reviewer
+- Consistency verification with design-sync (Design Doc only)
+
+**Out of scope** (redirect to appropriate skills):
+- New requirement analysis -> $recipe-design
+- Work planning or implementation -> $recipe-plan or $recipe-task
+
+**Responsibility Boundary**: This skill completes with updated document approval.
+
+Target document: $ARGUMENTS
+
+## Execution Flow
+
+### Step 1: Target Document Identification
+
+Check for existing documents in docs/design/, docs/prd/, docs/adr/.
+
+**Decision flow**:
+
+| Situation | Action |
+|-----------|--------|
+| $ARGUMENTS specifies a path | Use specified document |
+| $ARGUMENTS describes a topic | Search documents matching the topic |
+| Multiple candidates found | Present options to user |
+| No documents found | Report and end (suggest $recipe-design instead) |
+
+### Step 2: Document Type Determination
+
+Determine type from document path:
+
+| Path Pattern | Type | Update Agent | Notes |
+|-------------|------|--------------|-------|
+| `docs/design/*.md` | Design Doc | technical-designer | - |
+| `docs/prd/*.md` | PRD | prd-creator | - |
+| `docs/adr/*.md` | ADR | technical-designer | Minor changes: update existing file; Major changes: create new ADR file |
+
+**ADR Update Guidance**:
+- **Minor changes** (clarification, typo fix, small scope adjustment): Update the existing ADR file
+- **Major changes** (decision reversal, significant scope change): Create a new ADR that supersedes the original
+
+### Step 3: Change Content Clarification [Stop]
+
+**[STOP — BLOCKING]** Present change summary to user for confirmation.
+**CANNOT proceed until user explicitly confirms.**
+
+Ask the user to clarify what changes are needed:
+- What sections need updating
+- Reason for the change (bug fix findings, spec change, review feedback, etc.)
+- Expected outcome after the update
+
+Confirm understanding of changes with user before proceeding.
+
+### Step 4: Document Update
+
+Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Changes Required: [Changes clarified in Step 3]. Update the document to reflect the specified changes. Add change history entry."
+
+### Step 5: Document Review [Stop]
+
+**[STOP — BLOCKING]** Present review results to user for approval.
+**CANNOT proceed until user explicitly confirms.**
+
+Spawn document-reviewer agent: "Review the following updated document. doc_type: [Design Doc / PRD / ADR]. target: [path from Step 1]. mode: standard. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."
+
+**Store output as**: `$STEP_5_OUTPUT`
+
+**On review result**:
+- Approved -> Proceed to Step 6
+- Needs revision -> Return to Step 4 with review feedback (max 2 iterations):
+  Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Review Feedback to Address: $STEP_5_OUTPUT. Address each issue raised in the review feedback."
+- **After 2 rejections** -> Flag for human review, present accumulated feedback to user and end
+
+Present review result to user for approval.
+
+### Step 6: Consistency Verification (Design Doc only) [Stop]
+
+**[STOP — BLOCKING]** Present consistency verification results to user for final approval.
+**CANNOT proceed until user explicitly confirms.**
+
+**Skip condition**: Document type is PRD or ADR -> Proceed to completion.
+
+For Design Doc, spawn design-sync agent: "Verify consistency of the updated Design Doc with other design documents. Updated document: [path from Step 1]"
+
+**On consistency result**:
+- No conflicts -> Present result to user for final approval
+- Conflicts detected -> Present conflicts to user:
+  - A: Return to Step 4 to resolve conflicts in this document
+  - B: End and address conflicts separately
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Target document not found | Report and end (suggest $recipe-design instead) |
+| Sub-agent update fails | Log failure, present error to user, retry once |
+| Review rejects after 2 revisions | Stop loop, flag for human intervention |
+| design-sync detects conflicts | Present to user for resolution decision |
+
+## Completion Criteria
+
+- [ ] Identified target document
+- [ ] Clarified change content with user
+- [ ] Updated document via appropriate agent (update mode)
+- [ ] Spawned document-reviewer and addressed feedback
+- [ ] Spawned design-sync for consistency verification (Design Doc only)
+- [ ] Obtained user approval for updated document
+
+## Output Example
+Document update completed.
+- Updated document: docs/design/[document-name].md
+- Approval status: User approved

package/.agents/skills/recipe-update-doc/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-update-doc"
+  short_description: "Update design documents with review verification"
+  default_prompt: "Use $recipe-update-doc to update: "
+
+policy:
+  allow_implicit_invocation: false