recipe-front-design

Context: Dedicated to the frontend design phase.

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 quality standards
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

Load external-resource-context in Step 4 only when a named external source is required for the current design or verification decision.

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.

Orchestrator Definition

Core Identity: Coordinate frontend 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 Method:

• Scope and cost evidence -> performed by requirement-analyzer
• Scope confirmation -> performed by the orchestrator with user confirmation
• Codebase analysis -> performed by codebase-analyzer against the scope selected at Scope Confirmation
• UI fact gathering -> performed by ui-analyzer
• UI Specification creation -> performed by ui-spec-designer
• Design document creation -> performed by technical-designer-frontend
• Design Doc verification -> performed by code-verifier
• Document review -> performed by document-reviewer

Orchestrator spawns agents and passes structured data between them.

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 document routing
• Scope confirmation with the user, grounded in compact scope and cost evidence
• Codebase analysis of the frontend scope selected at Scope Confirmation
• Focused external resource hearing when a current design decision requires it
• UI fact gathering with ui-analyzer
• UI Specification creation with ui-spec-designer (prototype code inquiry included)
• One ADR per qualifying decision point found in the current scope, created and reviewed as one batch
• Design Doc creation with technical-designer-frontend
• Document review with document-reviewer

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

Requirements: $ARGUMENTS

Execution Flow

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 evidence result returns.

Step 2: Scope Confirmation

Confirm 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. Present additional UI or functional responsibilities with their current treatment and observable consequence for user judgment, and present repository mismatches that affect the requested outcome. User selection establishes product requirements and exclusions.
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 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. The Choice and Durability filters supply ADR decision points independently of scale. 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, invoke codebase-analyzer for the frontend scope selected at Step 2: "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]. layer: frontend. target_paths: [scopeEvidence.affectedFiles after Step 2]. focus_areas: responsibility ownership, state/data paths, contracts, and reuse."

Step 4: External Resource Hearing

After scope confirmation, identify whether a current UI or verification decision requires evidence unavailable from the repository, supplied artifacts, or a recorded resource. When it does, run the focused hearing from external-resource-context for that exact axis and persist its access method. Ask the user only when the missing access method controls the design decision. Otherwise record no external-resource dependency and continue.

Step 5: Prototype Inquiry

Use prototype code when the user supplied it or the UI target references it. Ask for a prototype path only when the UI target cannot otherwise be determined and the answer would change the UI specification. In all other cases set prototype_path to unavailable and continue.

When prototype_path is available, apply the subagents-orchestration-guide UI Spec rule to resolve prototype_reference_strength. Omit the field when no prototype is available.

Step 6: UI Fact Gathering Phase

Use the prototype path as an input when one was provided; otherwise set prototype_path to unavailable.

Invoke ui-analyzer agent: "exploration_mode: [mode from Analysis Assignment]. prior_evidence: [relevant Step 3 findings]. Gather UI facts for frontend design. requirement_analysis: { affectedFiles: [frontend affected files after Step 2] }. requirements: [Step 2 current requirements]. target_paths: [frontend affected files and directories after Step 2]. target_components: [frontend target components when known]. ui_spec_path: [path if an existing UI Spec covers this feature]. prototype_path: [path if provided]. externalResourceRefs: [{label, featureIdentifier} selected in Step 4, or []]. focus_areas: [remaining rendering, interaction, and visual questions]."

Step 7: UI Specification Phase

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. After UI fact gathering completes, create the UI Specification:

• Invoke ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists; read its binding requirements and only Product Context entries they explicitly cite]. Requirements and exclusions: [Step 2 current requirements and nonGoals]. Codebase analysis: [JSON from codebase-analyzer]. UI analysis: [JSON from ui-analyzer]. [Prototype code is at [user-provided path]. Prototype reference strength: [binding | reference]. Place prototype in docs/ui-spec/assets/{feature-name}/ | Prototype path unavailable; proceed from PRD/requirements and UI analysis.] External resource refs: [ui_analysis.externalResources.selectedRefs]."
• Invoke document-reviewer agent: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"
• Resolve needs_revision through Review Resolution with ui-spec-designer, then review the updated UI Spec. Route governing-source contradictions through Orchestrator Escalation Resolution before the user confirmation stop.

[STOP -- BLOCKING] Present UI Spec for user confirmation. Proceed after the user explicitly confirms the UI Spec.

Step 8: Design Document Creation Phase

Create appropriate design documents from the Step 2 scope and decision materials:

• Start with codebase analysis candidateDecisionPoints, then add a technical choice from UI analysis or the approved UI Spec when its evidence establishes at least two credible materially distinct options. Apply the Choice filter, then the Durability filter, to the complete candidate set.

• When the retained array is non-empty, invoke technical-designer-frontend once with document_to_create: ADRBatch, decision_points: [retained array], the requirements, and decision_materials: [only analysis material that changes the options, lifecycle cost, maintainability, or validity of 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. For Design Doc, invoke technical-designer-frontend with document_to_create: DesignDoc, adr_paths: [accepted ADR paths or []], the requirements, approved UI Spec, and decision_materials: [only analysis 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.
• Invoke code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]."
• Apply Review Resolution to every code-verifier discrepancy, using technical-designer-frontend in update mode for selected corrections and its bounded rerun rule. Carry the resolved verification summary, declines with reasons, and material limitations after the apply set becomes empty.
• Review the Design Doc: 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 analysis material that constrains this design]. verification_resolution: [resolved code-verifier evidence]."
• Resolve needs_revision through Review Resolution with technical-designer-frontend, then review the updated Design Doc. Route governing-source contradictions through Orchestrator Escalation Resolution. Reach the user confirmation stop after review succeeds.

[STOP -- BLOCKING] Obtain user confirmation using the shared Design Confirmation alignment. Proceed after the user explicitly confirms the design document.

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
• Codebase analysis completed before UI and design work
• Converged the requirement and carried exclusions into UI/design creation
• Confirmed the frontend design scope before codebase, UI, and design work
• External resource hearing completed when applicable
• UI analysis completed before Design Doc creation when applicable
• UI Specification reviewed and confirmed
• One ADR was created per qualifying decision point and the complete batch was reviewed once, or the empty set routed directly to Design Doc
• All document reviews passed

Output Example

Frontend design phase completed.

• UI Specification: docs/ui-spec/[feature-name]-ui-spec.md
• ADRs: docs/adr/[document-name].md paths or N/A
• Design document: docs/design/[document-name].md or N/A
• Continuation: User confirmed continuation