/02-refine

name: headless-step-refine
description: "Step 2 (refine) of the Hostinger Headless flow. Turns the user's seed — often just a domain — into a brief through conversation: asks what they want to build (purpose, audience, tone, pages, products, must-haves; images, local files, links all welcome), then *infers* the backend that fits (WordPress, Ecommerce, WordPress + Ecommerce, WordPress + WooCommerce for a one-site content+store, or Webapp for a custom app/SPA) — it never asks the user to pick a backend or a technology; the user confirms the plan in plain language, then it writes brief.md. Hostinger Ecommerce stays the default for selling; WooCommerce is chosen only when the user explicitly asks for it or wants content and a store on one WordPress site."

headless-step-refine

Find out what the user wants to build, guess which backend fits, and write it down. This is a **conversation, not a form**: the pasted prompt names a domain and nothing else, so everything about the site comes from talking to the user.

**Keep it short.** The only thing you must know is *what they are building* — enough to guess the backend. Every other question is skippable: the more the user gives, the better the site, but never hold the build hostage to refinement. Fill gaps with sensible defaults and say so in the brief.

> **Never ask the user to choose a backend or a technology.** Don't ask "WordPress or Ecommerce?", > don't present WordPress/Ecommerce/WooCommerce/Webapp as options, and don't surface the backend in a > multiple-choice UI. Open with **"What do you want to build?"** and infer the backend yourself in > Step 4 from what they describe (and whether they sell). The backend is a technical decision the flow > makes *for* the user — they confirm the **plan** (what the site is and does), not the plumbing. The > only exception is when the user *volunteers* a backend ("build it on WordPress", "use WooCommerce"): > then honour their choice and note it in the brief.

**In:** the domain (the workspace directory name), plus anything the user already shared. **Out:** `~/.hostinger/<domain>/brief.md`.

Nothing in this step touches Hostinger. It only asks, decides and writes.

---

Step 1 — Read the workspace, then the resume check

Read everything already in `~/.hostinger/<domain>/` (`state.json`, `connect.json`, any notes, images or files the user dropped there) — it all counts as input.

If `brief.md` already exists for this domain, **don't overwrite it**. Show the user a three-line summary (what the site is, its pages, the suggested backend) and ask: *keep it, or change something?* Keep → go to Step 6. Change → edit only what they asked for, then re-confirm (Step 5).

If the site is already provisioned (`site.json` exists), the backend is **fixed** — never change the Suggested backend on a provisioned site. Explain that switching backends means a new domain.

Step 2 — Gather what you already have

Before asking anything, collect what the user has already given you, so you don't ask for it again:

• **Inspect the directory the command was run in** — this is the biggest signal for the build mode

(Step 3). Look for an existing **frontend / webapp / commerce project**: a `package.json`, a framework config (`next.config.*`, `astro.config.*`, `vite.config.*`, `svelte.config.*`, `nuxt.*`), a `src/` or `app/` tree, `index.html`, a storefront/cart, etc. A real project here usually means the user **already has their own frontend** and mainly needs a Hostinger backend to wire it to — lean toward "bring your own frontend" in Step 3. If the folder has nothing site-like, assume they don't and lean toward "agent builds it".

• Anything in the pasted prompt beyond the domain (a sentence, a link, a screenshot).
• Files in the current project that look like site material (copy, logos, product lists, images).
• What the agent already knows about the user from local memory or this conversation (a prior build,

stack preferences, a frontend they always use).

• The domain name itself — a hint only (`coral-pottery.com` suggests pottery), never a conclusion.

Step 3 — Ask

If Step 2 already answers *what are you building* and *will they sell*, skip the Round 1–3 questions below, but still ask **Build mode** before moving on.

Otherwise open with one line and **wait for the user's answer**: *"Tell me what you want to build — a sentence is enough. Links, screenshots or files help too. Skip anything you don't want to answer."*

> **"What do you want to build?" is an OPEN question — ask it in plain prose and wait.** Never turn it > into a multiple-choice list of pre-baked site ideas ("Coffee shop / Travel blog / Portfolio …"): > that puts words in the user's mouth and defeats the point of asking. Let them describe it in their > own words. The structured question UI is only for genuinely *choice-shaped* follow-ups (selling > yes/no, which pages, tone adjectives, the build mode) — not for the opening question, and never for > the backend.

Ask in **short rounds of 2–3 questions**, and adapt each round to the previous answers. If your tool has a structured question UI (multiple choice with an "other" field), use it for the choice-shaped follow-up questions (pages, selling yes/no, tone) — **never for the opening "what do you want to build?" and never for the backend** (that's your decision, not theirs). **At most 3 rounds**, and stop early as soon as you can guess the backend and the user seems done — "just build it", "you decide", or a skipped question means *use defaults*, not *ask again*.

**Round 1 — what it is (the only required round):**

1. **What are you building?** The business or project, and what the site is for. 2. **Will you sell anything on it?** Physical products, digital products, services with checkout — or nothing. *This decides the backend.* Skip it only when the answer is already unmistakable ("an online shop for my candles", "my personal blog"); when in doubt, ask. 3. **Who is it for?*