Recipe Update Doc

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
3. [LOAD IF NOT ACTIVE] llm-friendly-context — clear prompts, handoffs, and generated artifacts

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

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.

1. 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 / technical-designer-frontend / prd-creator (update mode)
                        | (Design Doc only)
              code-verifier -> 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 and Layer Determination

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 or technical-designer-frontend | See layer detection below | | docs/prd/*.md | PRD | prd-creator | - | | 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
• 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]

For Design Doc updates, first verify the updated document against code:

Spawn code-verifier agent: "Verify the updated Design Doc against current code. doctype: design-doc. documentpath: [path from Step 1]. verbose: false. Focus especially on literal identifier referential integrity for concrete paths, endpoints, type names, config keys, and other exact identifiers changed in this update."

Store output as: $CODE_VERIFICATION_OUTPUT

For Design Doc updates: Spawn document-reviewer agent: "Review the following updated document. doctype: DesignDoc. target: [path from Step 1]. mode: composite. codeverification: $CODEVERIFICATIONOUTPUT. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."

For PRD or ADR updates: Spawn document-reviewer agent: "Review the following updated document. doc_type: [PRD or ADR]. target: [path from Step 1]. mode: composite. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."

Store output as: $STEP_5_OUTPUT

[STOP — BLOCKING] Present review results to user for approval. CANNOT proceed until user explicitly confirms.

On review result:

• Approved -> Proceed to Step 6
• Needs revision -> Return to Step 4 with review feedback (max 2 iterations):

Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Review Feedback to Address: $STEP5OUTPUT. 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)
• [ ] Ran code-verifier before document-reviewer for Design Doc updates
• [ ] Spawned document-reviewer and addressed feedback
• [ ] Spawned design-sync for consistency verification (Design Doc only)
• [ ] Obtained user approval for updated document

Output Example

Document update completed.

• Updated document: docs/design/[document-name].md
• Approval status: User approved

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinpr
• Source: shinpr/codex-workflows
• License: MIT

Install and usage instructions live in the source repository linked above.