recipe-design

Required Skills [LOAD BEFORE EXECUTION]

Before loading required skills, use wc -c to size the files and set both exec_command.max_output_tokens and the outer // @exec: {"max_output_tokens": N} budget to accommodate their contents, including the combined output of batched reads. Split oversized reads upfront; recover any truncated content before proceeding.

1. [LOAD IF NOT ACTIVE] documentation-criteria — document creation rules and templates
2. [LOAD IF NOT ACTIVE] subagents-orchestration-guide — agent coordination and review resolution
3. [LOAD IF NOT ACTIVE] requirement-convergence — requirements hearing and scope-confirmation output
4. [LOAD IF NOT ACTIVE] llm-friendly-context — document and review handoffs

Invocation rule: Start each named agent with spawn_agent and fork_turns="none". When invoking the same named agent again within this flow, use followup_task on its existing instance with the inputs specified for the current invocation.

Context: Dedicated to the design phase.

Orchestrator Definition

Core Identity: Coordinate design, make workflow decisions from compact specialist materials, and invoke specialists for analysis, authoring, and review.

Execution Plan: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification.

Execution Protocol:

1. Invoke agents for analysis and document work -- your role is to invoke sub-agents, select from their compact evidence against governing requirements, pass the selected material onward, and report results.
2. Run the design flow below in order:
   • Execute: scope evidence -> [Stop: Scope confirmation] -> optional PRD update/review/[Stop: PRD confirmation] -> codebase-analyzer -> optional ADR batch/batch review/[Stop: ADR-batch confirmation] -> Design Doc -> code-verifier/Review Resolution -> document-reviewer -> design-sync -> [Stop: Design confirmation]
   • [STOP — BLOCKING] At every [Stop: ...] marker -> Present status to user for confirmation and proceed after explicit confirmation.
3. Scope: Complete when design documents pass review and receive user confirmation

Workflow Overview

Requirements -> scope evidence -> [Stop: Scope confirmation]
                                      |
                optional PRD update/review -> [Stop: PRD confirmation]
                                      |
                             codebase-analyzer
                                      |
             optional ADR batch/review -> [Stop: ADR-batch confirmation]
                                      |
           Design Doc -> code-verifier -> Review Resolution -> document-reviewer
                                      |
                              design-sync -> [Stop: Design confirmation]

Scope Boundaries

Included in this skill:

• Compact scope and cost evidence from requirement-analyzer; the user owns product requirements and exclusions, while the orchestrator owns evidence comparison, readiness, scale, and ADR routing
• Scope confirmation with the user, grounded in compact scope and cost evidence
• Codebase analysis of the scope selected at Scope Confirmation before design creation
• One ADR per qualifying decision point found in the current scope, created and reviewed as one batch
• Design Doc creation with technical-designer
• Document review with document-reviewer
• Design Doc consistency verification with design-sync

Responsibility Boundary: This skill completes with approval of the Design Doc and its preceding ADR when required. Work planning and beyond are outside scope.

Requirements: $ARGUMENTS

ADRs record the considered options and one selected decision. PRDs and Design Docs contain only user-selected requirements and selected conclusions; evaluation-only ideas and unselected design candidates remain in the active workflow context.

Execute the process below within design scope.

Execution Process

Step 1: Scope and Cost Evidence

Apply the subagents-orchestration-guide Requirement Evidence Handoff, then invoke requirement-analyzer with that minimum contract.

Step 1 completes when the requirement-analyzer result is received. While it runs, apply the subagent-delegation independence boundary; Step 2 depends on the completed scope and cost evidence.

Step 2: Scope Confirmation

Confirm the requirements and determine Structural Scale from the user's wording and Step 1 scope and cost evidence:

1. Compare the retained user wording with the returned evidence. Matching facts are evidenced impact. When the repository exposes an additional functional responsibility, present its current treatment and observable consequence for user judgment. When the request assumes behavior the repository does not provide or cannot support as stated, present that mismatch and consequence for reconsideration. User-selected requirements remain current when no matching path was found; user selection establishes product requirements and exclusions. Evaluation requests, speculative ideas, and suggested mechanisms retain their original status.
2. Locate a related PRD and read its Converged Outcome, MVP scope, Future / Out of Scope, and open requirement fields. If the related PRD is ambiguous, ask the user to select or provide its path, or confirm none exists, before continuing.
3. When those fields match the current request and returned scope facts, use the PRD path as the current carrier and proceed directly to scope confirmation.
4. When a current carrier is absent, build the requirement-convergence record from the user's wording and judge readiness, using Step 1 scope and cost evidence for trade-offs, questions, and routing decisions. Mark an existing but incomplete or scope-mismatched PRD for update; otherwise mark the carrier as absent.
5. Determine Structural Scale and set prdRequired when the scale is Large and the current PRD carrier is absent.

Immediately before the stop, read requirement-convergence's references/scope-confirmation.md and render that output from the retained user wording and Step 1 evidence. Record Structural Scale and document routing under Workflow.

Request the listed user decisions and any separate document-route authorization still required, including a PRD path or approval to proceed without one when prdRequired is true. Re-run requirement-analyzer only when the user's answer changes its analysis target or the scope/cost evidence.

If prdRequired is true and the user neither provides a PRD path nor explicitly approves proceeding without a PRD, stop. This recipe does not create PRDs.

[STOP — BLOCKING] Wait for user confirmation before proceeding.

After confirmation, record the final scale. When the user's answer changes the analysis target or scope/cost evidence, re-run requirement-analyzer; otherwise update the convergence record directly. Use the current PRD path as carrier when available; otherwise use the compact convergence object.

Step 3: Upstream Confirmation and Codebase Analysis

When Step 2 marked an existing PRD for update, invoke prd-creator in update mode with that PRD path and the Step 2 convergence object. Review the updated PRD with document-reviewer using its path as target, then resolve findings through Review Resolution. After the review permits approval, present the updated PRD for user confirmation. Continue with its path as the carrier after approval.

[STOP — BLOCKING when a PRD was updated] Wait for user confirmation of the updated PRD.

When analysis is required under the subagents-orchestration-guide reuse rule, use the Fullstack Codebase Analysis assignment in subagents-orchestration-guide's references/monorepo-flow.md for a fullstack scope; otherwise invoke codebase-analyzer: "exploration_mode: [mode from Analysis Assignment]. Analyze the existing codebase to provide compact decision materials for ADR selection, minimal Design Doc creation, and verification. requirement_analysis: [Step 1 scopeEvidence after Step 2]. requirements: [Step 2 convergence record requirements]. prd_path: [current PRD path when present]. target_paths: [scopeEvidence.affectedFiles after Step 2]."

Apply the documentation-criteria Choice filter, then the Durability filter, to decisionMaterials.candidateDecisionPoints. adrDecisionPoints contains every current-scope point that passes both filters; an empty array routes directly to Design Doc. Record documentTypeRationale from the retained points.

Step 4: Design Document Creation

Create documents according to documentTypeRationale:

• When adrDecisionPoints is non-empty, invoke technical-designer once with document_to_create: ADRBatch, decision_points: [adrDecisionPoints], the requirements, and decision_materials: [only the Step 3 simplification, reuse, invalidation, option/cost, contract, and decision-changing unknown material relevant to those points]. Review all returned paths[] in one document-reviewer invocation using doc_type: ADRBatch and targets: [all paths]. Apply Review Resolution to the batch, rerun the batch review when an accepted correction changes a file, then present one ADR-batch confirmation request.

[STOP — BLOCKING when ADRs were created] Wait for one user confirmation of the reviewed ADR batch before creating the Design Doc.

Record every approved ADR file as Accepted when ADRs were created. Invoke technical-designer with document_to_create: DesignDoc, adr_paths: [accepted ADR paths or []], the requirement carrier, and decision_materials: [only Step 3 material that changes reuse, simplification, implementation validity, a selected ADR decision, a preserved contract, or verification]. The requirements define scope, and selected ADR decisions supply the current technical choices, revisable when a smaller sufficient design is supported.

Step 5: Code Verification

Review reception: Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. Invoke code-verifier agent: "Verify the Design Doc against the current codebase. document_path: [Design Doc path from Step 4]. doc_type: design-doc."

Apply Review Resolution to every discrepancy before document review, using technical-designer in update mode for selected corrections and its bounded rerun rule. When the apply set is empty, carry the resolved verification summary, declines with reasons, and material limitations to Step 6.

Step 6: Document Review

Invoke document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. requirement_context: [complete requirement context from Step 2]. decision_materials: [only Step 3 material that constrains this design]. verification_resolution: [resolved Step 5 evidence]."

Route the result before consistency verification:

• pass: continue
• needs_revision: apply Review Resolution with the creating technical-designer, then review the updated document
• rejected: apply Orchestrator Escalation Resolution. Continue after an evidence-based self-resolution; ask the user only when that procedure reaches a user-decision condition

Step 7: Consistency Verification

Invoke design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints."

Note: design-sync returns sync_status: "SKIPPED" when only 1 Design Doc exists. This is distinct from NO_CONFLICTS and MUST be reported as such to the user.

Request user confirmation using the shared Design Confirmation alignment.

Completion Criteria

• Obtained compact scope and cost evidence while the user retained product requirements and exclusions and the orchestrator handled comparison, readiness, scale, and routing
• Invoked codebase-analyzer and passed only decision-relevant material into ADR/Design Doc creation
• Converged the requirement and persisted the record
• Confirmed the design scope before codebase analysis and document creation
• Created one ADR per qualifying decision point and reviewed the complete batch once, or routed an empty decision-point set directly to Design Doc
• Applied Review Resolution to code-verifier discrepancies before document review
• Invoked document-reviewer and addressed feedback
• Invoked design-sync for consistency verification for Design Docs
• Obtained user confirmation for design document
• All [Stop: ...] markers honored with user confirmation

Output Example

Design phase completed.

• ADR: docs/adr/[document-name].md or N/A
• Design document: docs/design/[document-name].md or N/A
• Continuation: User confirmed continuation