git:20260608.652404a to git:20260915.2b5498a

---

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

---

<example>

<commentary>Demonstrates a direct user trigger asking to see layout options before building starts.</commentary>

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.

</example>

<example>

<commentary>Demonstrates the skill being invoked by prototype-builder as part of the coordinated build cycle.</commentary>

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.

</example>

## 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.