Agent Advisor

_phase: generate _title: "Generate — Recommendation Doc + Scaffolding" _requires_phase: estimate _input:

• design.json

• confirm.json _fragments:

• _id: generate-report _trigger: { _always: true } _file: phases/generate/generate-report.md _assemble: _file: phases/generate/generate-assemble.md _produces:

• diagram.md

• recommendation.md

• mini-brief.md

• recommendation-report.html _advances_to: migration-plan _preconditions:

• _check_phase_completed: estimate _on_failure: _halt_and_inform

• _check_file_exists: design.json _on_failure: _unrecoverable

• _validate_json: design.json _on_failure: _unrecoverable _postconditions:

• _check_file_exists: [diagram.md, recommendation.md, mini-brief.md, recommendation-report.html] _on_failure: _halt_and_inform

• _assert: "recommendation.md fills all 12 sections (business summary first, technical detail after) with the freshness footer; mini-brief.md carries the recommendation, top-3 signals, eliminated, model, and any io_wait/fedramp/region/cris notes set in design.json (a non-agent unit in a mixed system may show 'no model' when its model_recommendation is null); recommendation-report.html was generated (Step 5 is not optional); when design.json has >1 unit, recommendation.md contains the System topology section and the report one unit card per unit; every unit card whose design.json unit has a non-null model_recommendation contains the 'Why this model' card (rationale paragraph + collapsed 'Full model & migration detail' details block) rendered from unit.model_recommendation values, not invented" _on_failure: _halt_and_inform

• _assert: "recommendation.md's architecture-diagram section carries diagram.md's content INLINE — the Mermaid fenced block itself (and the ASCII fallback when build_diagram.py produced one), copied verbatim. A pointer such as 'see diagram.md' does not satisfy it: the recommendation doc is read on its own, often as the only artifact a reader opens, and the diagram is the section's whole content" _on_failure: _halt_and_inform

• _assert: "every score reported in recommendation.md, mini-brief.md, and the report is the engine's own number, exactly as scoring-result.json states it — no derived total, percentage, or invented denominator (scoring-result.json carries no maximum, so a form like '40/56' is a number the engine never produced)" _on_failure: _halt_and_inform

• _assert: "recommendation-report.html follows the v3 section spec from generate-report.md Step R1 — its numbered top-level sections are, in order: Summary, Assessment inputs, Recommendation(s), Target architecture, then (Temporal migration only when temporal units exist), Cost summary, Next steps, Generated artifacts, with the dynamic numbering R1 defines; an html whose top-level section structure was invented instead of taken from the template (a known failure mode after a mid-phase context compaction) fails this phase — re-read generate-report.md and regenerate" _on_failure: _halt_and_inform

Phase: Generate — Recommendation Doc + Scaffolding

Step 1 — Read inputs

Read $RUN_DIR/design.json. Read $RUN_DIR/estimate.json if it exists (all entry points except add_capabilities produce estimate.json; if it is absent — failure, or add_capabilities — Generate notes the absence in the report instead of inventing numbers). Load the winning runtime's service card and ${CLAUDE_PLUGIN_ROOT}/skills/agent-advisor/references/decision-refs/model-selection.md. (Same exception as Design Step 2: a serverless_workers unit has NO <verdict>.md card — do not attempt to load one; derive its content from temporal.md + poc-shapes.md.)

Step 2 — Build the architecture diagram

Load references/diagram/build-diagram.md and follow it to produce $RUN_DIR/diagram.md (Mermaid + ASCII), then embed it into Section 4 of the recommendation doc.

Embed means paste the content, not link to it. Copy diagram.md's fenced Mermaid block (and its ASCII fallback) into Section 4 verbatim. "See diagram.md" leaves the section empty for anyone reading recommendation.md on its own, which is how it is usually read — it is the artifact that gets forwarded, and the diagram is that section's entire content.

Step 3 — Fill the recommendation document

Load references/output-templates/recommendation-doc.md. Fill ALL 12 sections. Business summary first, technical detail after (single layered doc — do not fork by audience). Write to $RUN_DIR/recommendation.md. Append the freshness footer.

For migrate: also fill Section 9 (Bedrock model) with the coarse family mapping (e.g. "GPT-4o → Claude Sonnet 5 family") and a note that detailed pricing/TCO come from the migration plugins — no dollar figures. Section 10 (cost magnitude) presents the per-unit target-state bands from estimate.json and notes that the migration TCO comparison and current-spend delta are produced by the migration plugins.

Section 3c — Temporal migration (conditional: only if ANY design.json.units[].workload_class == "temporal_worker_poll" — the temporal block has no units field, so gate on the unit list, matching generate-report.md's TEMPORAL_UNITS_PRESENT): orchestrate §3c content from design.json.temporal + decision-refs/temporal.md. Load the commercials/runbook text from decision-refs/temporal.md (never restate). The Bedrock follow-up gate runs HERE conditionally:

• AskUserQuestion: "Move Activity LLM calls to Bedrock as part of this migration?"

• Yes → append "Bedrock migration" section to recommendation.md §3c: (a) point to /aws-startup-advisor:llm-to-bedrock skill as follow-up, (b) REQUIRE replay safety per decision-refs/temporal.md runbook 3 (keep Workflow determinism against recorded history, or isolate via Worker Versioning / new task queue). If deeply-coupled AI integrations flagged, note the rewrite must respect the shim.

• No → append "Later, optional: Bedrock" section with the same replay-safety pointer.

No Step Functions comparison section — the scope note at the top of the plan already states the orchestration layer stays on Temporal. If the user asks why, answer in chat per decision-refs/temporal.md ("If the user asks") — do not add it to the plan.

Step 4 — Lightweight scaffolding (Build paths only)

Skip this step entirely for migrate (execution artifacts belong to the downstream plugins). For Build paths:

• AgentCore + Harness → write a minimal harness.json skeleton with the selected services. Include the exact invocation_model_id only when live_verification.status == "passed"; otherwise use TODO: verify model id and state that account access is unverified.

• AgentCore + Framework / other runtimes → write a minimal framework starter note (entrypoint contract: /invocations POST + /ping GET for AgentCore) + the same verified invocation ID or explicit TODO placeholder. Write scaffolding under $RUN_DIR/scaffold/. Keep it minimal — heavy IaC hands off.

Step 4.5 — Write the mini-brief to $RUN_DIR/mini-brief.md (delivered by the Step 5.5 sidebar)

Compose the mini-brief — it is the deliverable of the whole advisor flow — and WRITE IT TO $RUN_DIR/mini-brief.md (a file, not just chat text; Step 5.5 re-reads it):

• Recommendation (runtime + deployment model), Why (top 3 signals), Eliminated, Model, and a pointer to $RUN_DIR/recommendation.md.

• For each model-bearing unit, include API path, path-specific model ID, CRIS/invocation status, [BLOCKS], evaluation mode, and live verification status. Never describe model access as runnable unless live_verification.status == "passed".

• Any warnings from the scoring result (e.g. 5 TPS).

• If design.json has io_wait_tco_note == true: the I/O-wait TCO point (AgentCore bills $0 during model/human waits — a cost edge for spiky/HITL traffic; no dollar figures).

• When set: fedramp_note (FedRAMP WIP — verify + GovCloud fallback), region_availability_note (runtime not in the user's region — nearest supported), and cris_note (geo-CRIS vs global-CRIS data-residency choice for EU/GDPR).

Step 5 — Generate HTML recommendation report

You MUST produce $RUN_DIR/recommendation-report.html — it is a required output of this phase, not optional. Load references/phases/generate/generate-report.md and follow it to write the file, then open it in the user's browser.

Scope of "non-blocking": only the browser-opening and a genuine build failure are non-blocking — NOT the generation itself. So:

• If the open/xdg-open command fails (no GUI): print Report ready — open: file://$RUN_DIR/recommendation-report.html and continue.

• If writing the HTML genuinely errors: log the specific warning and continue.

• Never SKIP this step to reach Step 5.5 faster. Step 5.5 checks that the file exists (below) — if it is missing, you skipped Step 5 and must come back and do it.

Step 5.5 — Recommendation review sidebar (BLOCKING — the user must see and confirm the recommendation before any gate)

Precondition check (do this FIRST, before composing the sidebar): confirm $RUN_DIR/recommendation-report.html exists on disk. If it does NOT, Step 5 was skipped — go back and run Step 5 now (generate the report + open it) before proceeding. Do not present this sidebar without the report having been generated.

This is its own turn, separate from every gate. Send ONE message whose body is the full mini-brief pasted from $RUN_DIR/mini-brief.md, followed in the SAME message by an AskUserQuestion:

[contents of $RUN_DIR/mini-brief.md]

"This is the recommendation. Take a moment to review it (full detail in $RUN_DIR/recommendation.md) — does it look right before we talk about next steps?"

• Looks good — continue → record the confirmation (below) and proceed to Step 6.

• Explain more first → answer the user's questions on the recommendation (from recommendation.md / design.json — no new scoring), then re-ask this sidebar.

• Something's off — revisit an answer → identify which clarify answer changed, update answers.json, re-run scoring, and redo Design → Generate. Do NOT proceed on a recommendation the user disputes.

On "Looks good — continue": read-merge-write .phase-status.json and set top-level "recommendation_reviewed": true.

Mechanical gate rule: Steps 6 and 7 MUST NOT ask Gate 1 or Gate 2 unless .phase-status.json has recommendation_reviewed == true. If it is absent, you skipped this sidebar — go back and run it. This ordering is not optional and does not collapse into the gate question: the user confirms they have SEEN the recommendation first, and only then is asked what to do next. (Resume-safe: if the session breaks after confirmation, the flag survives and the sidebar is not re-asked.)

Because the sidebar delivered the brief, the gates below only need a one-line recap (runtime + deployment model + model), not the full brief.

Step 6 — Migration-plan gate (Gate 1)

Precondition: .phase-status.json.recommendation_reviewed == true (set by Step 5.5). Absent → run Step 5.5 first; never ask this gate without it.

Applicability (skip this step when none applies — mark phases.migration_plan = "not_applicable"):

• entry_point == migrate → always offer.

• entry_point == build_deploy → offer ONLY if Discover ran and $RUN_DIR/context-signals.json.model_provider ∈ {openai, anthropic, google-genai} — i.e. something real exists to migrate. Key absent, none, or bedrock → not applicable.

• entry_point == build_scratch → never (nothing existing to migrate).

For migrate, FIRST load references/handoff/handoff-migration.md and follow its Step 1 to write $RUN_DIR/handoff-summary.md (it is both the human-readable handoff artifact and the Stage 2 injection payload source). Then ask Gate 1 — a one-line recap (runtime + deployment model + model; the full brief was confirmed at Step 5.5), followed by the AskUserQuestion in the same message:

Recommended: <runtime> + <deployment model>, model <model> (details: recommendation.md).

"Do you want a complete migration plan for this workload? I'll generate it here using this plugin's migration engine, reusing the decisions we already made (runtime, deployment model, memory). It will analyze your code and may ask a few extra questions."

• Yes — generate the migration plan → set phases.migration_plan = "pending"; after Step 7 the state machine loads references/phases/migration-plan/migration-plan.md.

• No → set phases.migration_plan = "skipped". For migrate, keep the classic pointer: follow handoff-migration.md Steps 2–4 (direct the user to /aws-startup-advisor:llm-to-bedrock or gcp-to-aws with handoff-summary.md).

Step 7 — Write state and branch

Set phases.generate = completed (read-merge-write). Then branch:

1. Gate 1 answered Yes → next phase is migration_plan: load references/phases/migration-plan/migration-plan.md. Gate 2 is offered from that phase's Step 6.

2. Otherwise, if entry_point ∈ {build_scratch, build_deploy}: ask Gate 2 for the primary unit's effective_runtime — any of agentcore / ecs / eks / lambda / lambda_microvms (the primary is always an agent unit per Clarify's scope gate). In a MULTI-unit system, each non-primary unit still gets its own POC per poc.md Step 3 dispatch (incl. batch / fargate / serverless_workers, and a model-less non-agent unit omits Bedrock wiring). Precondition unchanged (recommendation_reviewed == true). Give a one-line recap (runtime + deployment model + model), followed by the AskUserQuestion in the same message:

   Recommended: <runtime> + <deployment model>, model <model> (details: recommendation.md).

   "Do you want a deployable proof-of-concept for this recommendation on <runtime>? I'll generate the agent code, deployment plan, and scripts."

   • Yes → set phases.poc = "in_progress" (persist the confirmation), then load references/phases/poc/poc.md (it asks which POC mode first).

   • No → set phases.poc = "skipped"; the advisor flow is complete.

3. Otherwise (migrate without a plan): the Step 5.5 sidebar already delivered the brief; close with a short completion message pointing at recommendation.md — the advisor flow is complete.

Non-interactive runs (seeded). When $RUN_DIR/seed.json exists (clarify.md Step 2.5), its gates block answers these gates instead of AskUserQuestion: gates.migration_plan and gates.poc, each accept or decline. A gate the seed does not mention is DECLINED — never accept a gate on the user's behalf, because both gates spend real time and money. Persist the resolved status exactly as the interactive path does (phases.poc = "in_progress" before poc.md loads on accept, "skipped" on decline) so a resumed run does not re-ask. Record in $RUN_DIR/UNANSWERED.md that the gate was resolved from the seed default rather than by a human whenever the seed was silent.

Note: for migrate WITH a completed migration plan, Gate 2 is asked at the end of migration-plan.md (its Step 6), using the same wording as point 2 above.

Maturity/readiness output extension

Recommendation.md and mini-brief.md must state target maturity, readiness status, concrete gaps, tier-appropriate release/evaluation gates, recommendation status, and every deferred verification requirement. Label the mini-brief Provisional whenever design.json.recommendation_status == "provisional"; it must say that no runtime decision, pricing claim, or launch gate relying on deferred evidence is final. Include the AgentCore I/O-wait billing benefit only when Design recorded current-run verification; otherwise report the check as pending without a static billing result.