Mobile Prototype

Work out what the screens are and how they connect before anyone designs or builds them, working like a UX designer would. The prototype is a rough draw.io sketch on purpose: it keeps the discussion on features, states and branches, not on colours and spacing.

documents → proposals (gate A) → open questions (gate B) → draw.io sketch, flow locked (gate C)
          → optional: design system + final-look screens (gates D1, D2) → handoff

Paths in this file are relative to this skill's directory (scripts/…, references/…, assets/…). The user's project is the current working directory.

Non-negotiables

1. Documents propose, the user decides. An answer found in a document is a proposal until the user approves it. Record who decided what.
2. Ask only what changes the experience. Conflicts between documents and unknowns that change a journey, a state or navigation get asked. Cosmetic choices you decide yourself and record.
3. The flow lives in one file. docs/prototypes/flow.json is the source of truth; the draw.io file, the handoff's screen inventory and the final-look screens are generated from it by scripts. Never hand-write draw.io XML or HTML, and never place shapes or route arrows yourself.
4. Rough on purpose. The sketch uses plain boxes in a hand-drawn style. No brand colours, no real components, no pixel decisions before the flow is locked.
5. Numbered and untangled. Every screen frame carries a serial number (S1, S2, … in flow order), and people refer to screens by it everywhere. Review markup (numbers, remarks) stays outside the phone frame or in the frame's note. sketch.mjs refuses to draw crossing or shared arrows, arrows over screens, overlapping screens or labels in the way: never show a sketch that didn't pass --check, and fix a failure in flow.json (see "When the check fails" in references/sketch-spec.md), not in the diagram.
6. Stop at every gate, and say what to read. At each stop, end your turn: don't start the next phase ahead of the approval. Follow Stops below.
7. Stop at a locked flow. Deliver the sketch and a handoff package. Do not build a clickable app, and do not generate Compose, SwiftUI, Kotlin, Swift or production web code.
8. Each platform behaves like itself. The sketch is one flow for every platform in scope (P5); where Android and iOS differ (back, dialogs versus sheets, permission rules) say so in the frame's note. Follow references/platforms/<platform>/conventions.md.
9. Everything lands in files in one prototype folder inside the project, chosen by the user before the first file is written, so a fresh session can resume.
10. First how it works, then how it looks. The design phase is optional, starts only after the flow is locked (gate C) and only when the user chooses it, and never blocks the handoff.
11. draw.io tooling helps; it never blocks. If the draw.io MCP tools aren't loaded, say so in one line and carry on: the scripts write and open the diagram without them.

Workspace (in the user's project)

This document calls the prototype folder docs/prototypes/ (the recommended location); wherever you read that path, use the folder the user chose in Phase 1. It must be inside the project: if the user names a path outside it (another repository, the home folder, /tmp), say the files have to stay in this project so they travel with it, and ask again. scaffold.mjs refuses such a path too.

docs/prototypes/
├── README.md        ← the reading guide for the user
├── flow.json        ← journeys, screen states, transitions (you edit this)
├── flow.drawio      ← the sketch, generated from flow.json
├── HANDOFF.md       ← final deliverable for the native team
├── look/            ← design phase only: generated final-look screens
└── notes/
    ├── STATE.md            ← phase, gates passed, next step (resume point)
    ├── INPUTS.md           ← document inventory + fact register with citations
    ├── CLARIFICATIONS.md   ← every question: source, proposal, status, decision
    ├── DECISIONS.md        ← approved decisions and recorded assumptions
    └── DESIGN.md           ← the visual direction (design phase only) + THEME-REPORT.md

node scripts/scaffold.mjs --out <folder> --name "<App>" creates README.md, flow.json and the four notes from templates, and never overwrites. Fill in what it creates; don't invent other files. The other scripts find the folder by its notes/STATE.md, so they need no --out unless the project holds more than one prototype folder.

Stops

The work pauses for the user only at these stops: Inputs (Phase 1), gate A (Phase 2), gate B (each Phase 3 round), gate C (Phase 4), D1 / D2 (Phase 5) and the handoff (Phase 6). At every stop from gate A on, before ending your turn:

1. update docs/prototypes/README.md — Where we are, Read now, and each new file marked you, reference or agent;
2. record the stop in STATE.md under Waiting on user;
3. end the message with the short reading guide.

Read references/stops-and-reading-guide.md at the first stop: it has what the user reads at each stop and the exact form of the guide. Everything the user must decide goes in the message.

Phase 0 — Setup and resume

1. Look for an existing prototype folder: docs/prototypes/notes/STATE.md, the older default prototype/notes/STATE.md, or a notes/STATE.md next to a flow.json elsewhere in the project. If there is one, that is the prototype folder: don't ask for it again. Read STATE.md and every file in notes/, tell the user in two lines where things stand, and continue from the recorded next step; if that stop still waits on the user, repeat what it needs. A flow.json without appScreens predates screen names: migrate it before drawing again (Migrating an older flow.json in references/sketch-spec.md).
2. Run node scripts/check-update.mjs. If it reports a newer release, pass on its one line and update command, and carry on with the installed version; don't update unless the user asks. A prototype whose STATE.md records an older skill version may need migrating (CHANGELOG.md in the skill's repository says what changed).
3. Check whether the draw.io MCP tools are available in this session: a tool whose name ends in open_drawio_xml (for example mcp__drawio__open_drawio_xml).
4. If they are missing, run node scripts/check-drawio-mcp.mjs --host <this agent> and show the result. Ask before changing the user's configuration, then run --configure --host <this agent> (without --host it configures every agent installed). A new server loads only after a restart: say so, record it in STATE.md, and carry on. Details: references/drawio-setup.md.

Phase 1 — Discover the inputs

1. If the user named files, use those. Otherwise run node scripts/discover-inputs.mjs --root . to find specs, architecture, design, API contracts and images, plus platform signals with a suggestion. This step only reads; nothing is created yet.

2. Ask where the prototype files should go (the Inputs stop), unless the user already named a folder or Phase 0 found one:

   Where should I put the prototype files? I recommend docs/prototypes (created if it doesn't exist). Reply "ok" for that, or give another folder in this project.

   In the same message show the availability table — Spec / Architecture / Design / API / Other, plus the platform suggestion — with the files found for each. Ask the user to confirm the target platform (don't assume both), which documents are authoritative, which to ignore, and whether anything is missing (a design folder, a Figma link). Leave the table out when the user named the files and there is nothing to ask about them. End your turn.

3. "ok", "yes" or no preference means docs/prototypes. A relative path is relative to the project root; an absolute one must be inside the project (see Workspace). Then run node scripts/scaffold.mjs --out <folder> --name "<App>" and record the folder in notes/STATE.md.
4. Read every confirmed document in full (images too — look at them). Record the inventory and a fact register (ID, fact, source file § section) in notes/INPUTS.md.
5. Adjust for what is missing (references/document-intake.md). Without a spec, get at least a written feature description from the user before going on.

Phase 2 — Answer from the documents → approval gate A

Work through references/question-bank.md. For each question in scope, try to answer it from the fact register and classify it (full rules in references/clarification-protocol.md):

Write every item to notes/CLARIFICATIONS.md. Then present A and B items to the user as one compact table (question · proposed answer · source · confidence) and ask them to approve all, or correct by ID. Only approved items move to DECISIONS.md. Mention the E defaults in one line so the user can object. If there are C/D items, say how many questions will follow at gate B.

Two things are always settled here or in Phase 3, and recorded in STATE.md:

• Target platforms (P5): Android, iOS or both. Propose it from the platform signals with citations; if there are none, or they disagree, ask. Never assume both.
• Sketch style (P6): ask in one line under the table — it is the user's preference, not something the documents answer: wireflow (the whole flow on one page per journey), click-through (a map, then one page per screen with clickable buttons) or both. With no preference, use the wireflow; the same flow.json produces all three.

Stop here (gate A). Don't write flow.json or draw anything yet, even as a draft: the flow depends on the scope the user is about to approve or correct.

Phase 3 — Close the gaps with the user → gate B

Ask the C and D questions, most blocking first, at most four per round. Each question gives the evidence from the documents, two to four concrete options, and your recommended option first with a one-line reason. Use the host's structured-question tool when there is one (for example AskUserQuestion in Claude Code); otherwise ask as a numbered list in chat.

Record each answer immediately. Answers can raise new questions — classify and queue them the same way. If the user says "you decide" or defers, record your choice as an assumption flagged for review. Gate B passes when no blocking (C/D) item is open. After three rounds, offer to proceed with the remaining items as flagged assumptions rather than keep asking.

Each round is a stop. Once gates A and B have both passed (B passes at once when there are no C/D items), go straight on to Phase 4.

Phase 4 — Sketch the flow → gate C

1. Write the flow in docs/prototypes/flow.json (format and element list: references/sketch-spec.md):

   • every app screen once in appScreens, with its one name. A frame gives its screen, its state and, where it matters, its entry condition ("First launch"); it has no title of its own, so a state or an entry condition never becomes a second name for a screen;
   • one journey per user goal in scope;
   • one frame per screen state the decisions require — the content state, and also empty, loading, error, offline, permission denied, validation error, and each dialog or sheet. Main path first, in the order the user meets the screens; a branch (a dialog, an error) names the screen it hangs under;
   • one flow per transition, labelled with what the user does ("tap Save", "Back with changes"), starting from the control that triggers it.

   Use realistic copy from the documents, not lorem ipsum.

2. Generate and check: node scripts/sketch.mjs --style <wireflow|click-through|both> writes docs/prototypes/flow.drawio; node scripts/sketch.mjs --check must pass. Then go through references/sketch-review.md. Fix flow.json and generate again; don't show a sketch with warnings you haven't looked at.
3. Show it: node scripts/sketch.mjs --style <style> --open. Give the user flow.drawio as a link and how to open it and find its pages, as sketch.mjs prints it (VS Code with the draw.io extension, draw.io Desktop or app.diagrams.net; not an Android Studio plugin).
4. Stop (gate C). In chat, give a short text outline of the journey (S-numbers and the arrows), the decisions you made on the user's behalf and the flagged assumptions, and ask them to lock the flow or say what to change.
5. Changes: treat feedback as new clarifications — record, change flow.json, regenerate, show again. If the user edited flow.drawio by hand, the script refuses to overwrite it: read their version (it is XML), carry every change into flow.json (ask if one is unclear), then run sketch.mjs --force (it keeps their version as flow.drawio.bak). Gate C passes only on an explicit approval; record it in STATE.md and DECISIONS.md.
6. After the approval, offer the design phase in one line (design system and final-look screens, or go straight to the handoff). Don't push it.

Phase 5 — Optional design phase (only if the user chooses it)

Read references/design-phase.md and follow it. The locked flow.json is the input; the user picks a direction from style tiles (gate D1) and approves the final-look screens (gate D2). The design phase changes how screens look, never the flow. If it is skipped or stopped, go to Phase 6.

Phase 6 — Handoff and stop

Run node scripts/handoff.mjs: it creates docs/prototypes/HANDOFF.md and fills its screen inventory, transitions and pages from flow.json. Write the other sections following references/handoff-package.md; node scripts/handoff.mjs --check must pass. Update STATE.md to complete, and README.md so Read now is HANDOFF.md alone. Tell the user where everything is and stop — native implementation is a separate task.

When guidance conflicts

1. The user's explicit decisions (in DECISIONS.md).
2. The supplied documents — the spec decides what the product does; the architecture decides what is feasible. Conflicts between them are class C and go to the user.
3. The platform conventions (references/platforms/<platform>/conventions.md).
4. The approved visual direction (DESIGN.md), for the look only; it never changes the flow or overrides the platform conventions.
5. Your own taste.