visual-companion

name	visual-companion
plugin	exploration-cycle-plugin
description	Presents layout options to the SME in plain language before any prototype construction begins. Invoked after the Discovery Plan is approved to confirm visual structure and direction. Trigger phrases: "what should it look like", "show me some layout options", "let me see the design options before we build". Also invoked by prototype-builder after plan approval.
allowed-tools	Read, Write

Dashboard Intercept

Before doing anything else, silently check for exploration/exploration-dashboard.md.

• If the file EXISTS:
  • Read the file and check the status. If status is Complete, proceed standalone.
  • If status is In Progress or TBD:
    • Check for the presence of the <ORCHESTRATOR_DISPATCH> tag in the immediate context.
    • If the tag is PRESENT:
      • Extract and verify the authorized_skill, phase_number, and expected_output attributes from the <ORCHESTRATOR_DISPATCH> tag.
      • If authorized_skill matches "visual-companion" AND phase_number matches the dashboard phase:
        • Proceed with this skill's logic. (You are authorized by the orchestrator).
        • Note: The orchestrator manages dispatch token lifecycle. This tag is valid for the current phase only — it becomes stale once the orchestrator advances the dashboard in Block 6.
      • If verification fails (mismatched name or stale phase):
        • Stop immediately. Announce: "Orchestrator dispatch verification failed. Returning to dashboard."
        • Return control. Invoke skill: exploration-workflow. Stop generating output.
    • If the tag is ABSENT or malformed:
      • Stop immediately. Do not continue.
      • Announce: "It looks like you have an active Exploration Session. Let me take you back to your session dashboard."
      • Return control to the orchestrator. Invoke skill: exploration-workflow. Stop generating output from this skill.
• If the file DOES NOT exist: Proceed standalone.

Demonstrates a direct user trigger asking to see layout options before building starts. User: What should it look like? Agent: Reads the most recent Discovery Plan for context, then presents three plain-language layout options labelled Option A, Option B, and Option C — adapted to the specific problem domain — and asks the SME which feels closest to what they had in mind. Demonstrates the skill being invoked by prototype-builder as part of the coordinated build cycle. User: [dispatched by prototype-builder after Discovery Plan approval] Agent: Reads the Discovery Plan silently, presents three contextually adapted layout options in plain language, confirms the SME's selection, and writes the confirmed layout direction to exploration/captures/layout-direction.md before signalling ready to build.

Skippable Phase

This phase may be skipped for brownfield sessions or simple features where the design is straightforward. If skipped, it will be marked - [~] in the dashboard. The downstream Phase 3 skill handles missing layout direction gracefully.

Role

This skill is invoked after the Discovery Plan is approved. Its purpose is to confirm the structure and shape of the output before any building or drafting starts. For software, this means UI layout. For non-software work, this means document structure, process flow shape, or analysis format. It ensures the SME has a clear picture of what they are agreeing to before anything is created.

Session Flow

Step 1 — Read context and determine output type

Read the most recent file in exploration/discovery-plans/. Understand the problem domain, stakeholders, and success criteria before proposing anything. Do not skip this step.

Determine the output type from the Discovery Plan and session type:

• Software UI — the output is a screen, page, or interactive interface
• Process or workflow — the output is a business process, approval chain, or operational flow
• Document or analysis — the output is a report, requirements doc, policy, or strategic plan
• Mixed — some combination of the above

Step 2 — Present 3 options (adapted to output type)

Offer 3 structure options adapted to the context of the Discovery Plan. Describe each in plain language (2–4 sentences). No technical terms. No code. No wireframes. Words only.

Label them Option A, Option B, Option C.

For software UI outputs, adapt these starting points:

• Option A: A single-page view with a summary at the top and details below — good when people need to see everything at once and make decisions without switching screens
• Option B: A step-by-step flow that walks the user through one thing at a time — good when there's a sequence of decisions, approvals, or actions that need to happen in order
• Option C: A two-panel layout with a list on the left and details on the right — good when people need to browse through a number of items and compare them before deciding

For process or workflow outputs, adapt these starting points:

• Option A: A linear flow — steps happen in a fixed order from start to finish, good for simple processes with no branches
• Option B: A decision-tree flow — the path branches based on conditions or approvals, good when different situations lead to different actions
• Option C: A swimlane view — shows who does what at each stage, good when multiple people or teams are involved and handoffs matter

For document or analysis outputs, adapt these starting points:

• Option A: Executive summary up front with supporting detail sections — good when the audience wants the answer first and the reasoning second
• Option B: Problem → Analysis → Recommendations structure — good when the audience needs to follow the logic to be convinced
• Option C: Comparison format with side-by-side options — good when the deliverable is about choosing between alternatives

After presenting the three options, ask:

"Which of these feels closest to what you had in mind? Or if none of them fit, describe what you're picturing and I'll work with that."

Step 3 — Confirm selection

Reflect back the chosen option in one sentence. For example:

"Got it — we'll go with a step-by-step flow so your team can move through each approval in order."

Then ask: "Is there anything you'd like to adjust about that?"

Wait for the SME's response before proceeding.

Step 4 — Save direction

Write exploration/captures/layout-direction.md with this structure:

# Layout Direction

**Selected:** [Option letter and name]
**SME notes:** [any modifications or specific requests the SME mentioned]
**Confirmed:** [date]

Step 5 — Signal ready

Announce: "Layout confirmed — Phase 2 is complete."

Completion — Return to Orchestrator

If operating within an active Exploration Session (i.e., exploration/exploration-dashboard.md exists and **Status:** is not Complete):

1. Say to the user:

   "Returning to your session dashboard now."

2. Return to the orchestrator. Use the Skill tool: skill: "exploration-workflow". After invoking it, stop generating output from this skill. If the Skill tool is not available in your harness, tell the user: "Please run /exploration-workflow to continue your session."

If operating standalone (no dashboard file, or **Status:** Complete), the skill is complete.