figloops-init

Files (1)

• SKILL.md

SKILL.md (first lines)

## Setup
Resolve `FIGLOOPS_PLUGIN_DIR`: the parent of this skill's parent directory (e.g., `.../figloops`). If `FIGLOOPS_PLUGIN_DIR` env var is set, use it directly. Otherwise resolve from the skill file path, print the resolved path, and write it to `.env` in step 9. Scripts: `cd "<CONSUMING_REPO>" && "<PLUGIN_DIR>/node_modules/.bin/tsx" "<PLUGIN_DIR>/scripts/<name>.ts" <args>`. Always double-quote all paths.

## Style
Tables for 2+ comparable fields (escape `|` → `\|`, newlines → spaces in cells). Icons: `→` checking · `✓` pass · `✗` fail · `⚠` warning. `AskUserQuestion` options carry no descriptions. Blockquote + bold for plain-text input prompts.

## Errors
TS exits non-zero → relay stderr verbatim. MCP fail → relay error and abort. State load fail → abort.

---

## Wizard

### Step 0 — Welcome banner

Print this first, before any tool calls:

````
```
███████╗██╗ ██████╗ ██╗      ██████╗  ██████╗ ██████╗ ███████╗
██╔════╝██║██╔════╝ ██║     ██╔═══██╗██╔═══██╗██╔══██╗██╔════╝
█████╗  ██║██║  ███╗██║     ██║   ██║██║   ██║██████╔╝███████╗
██╔══╝  ██║██║   ██║██║     ██║   ██║██║   ██║██╔═══╝ ╚════██║
██║     ██║╚██████╔╝███████╗╚██████╔╝╚██████╔╝██║     ███████║
╚═╝     ╚═╝ ╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝     ╚══════╝

Welcome to figloops — user feedback loops for web prototypes.
Setting up your project now…
```

Before we begin, you'll need:

- **Figma MCP** connected to this Claude Code session — https://github.com/figma/mcp-server-guide
- **Figma Personal Access Token** — https://www.figma.com/developers/api#access-tokens
- **A Figma file URL** to push screenshots into *(recommended: a dedicated file — figloops creates new pages on every round)*
- **Your app URL** — local (`http://localhost:3000`) or deployed (Vercel, Netlify, GitHub Pages, etc.)
````

### Step 1 — MCP preflight

Print `→ Checking for Figma MCP write tool…`. Confirm `use_figma` (or `figma_execute` from southleft/figma-console-mcp) is available. On fail: print `✗ No Figma MCP write tool found`, tell user to install the official Figma MCP server at https://github.com/figma/mcp-server-guide, abort.

Auth probe:
- Check for token: `FIGMA_TOKEN` in process env, or a `FIGMA_TOKEN=` line in `.env`. Extract the value without running any script.
- If no token found: print `→ No FIGMA_TOKEN found — will collect in Step 5.` and continue. Do NOT call validate-token.ts.
- If token found: print `→ Verifying Figma auth…`, then run:
  `FIGMA_TOKEN=<token> "<PLUGIN_DIR>/node_modules/.bin/tsx" "<PLUGIN_DIR>/scripts/validate-token.ts"`
  - On success: print `✓ Auth confirmed — **<handle>**`
  - On fail (bad token / 401): print `✗ Figma auth failed — <error>` and abort.

### Step 2 — Existing project detection

**2a. `feedback/state.json`** — if present:
```
question: "An in-progress round already exists. What do you want to do?"
header: "Existing round"
options:
  - label: "Resume — exit init, just run /figloops:go"
  - label: "Archive — rename state.json to a backup and start fresh"
  - label: "Purge — delete all figloops files and start fresh"
  - label: "Cancel — don't change anything"
```
- Resume: read `currentRound` and `currentPhase` from the file. Print `"Round <N> phase <phase> is in progress. Run /figloops:go to continue."` Abort.
- Archive: rename to `feedback/state.<YYYYMMDD-HHMMSS>.json.bak` (use `date '+%Y%m%d-%H%M%S'`). Tell user the backup path. Continue.
- Purge: run `"<PLUGIN_DIR>/node_modules/.bin/tsx" "<PLUGIN_DIR>/scripts/uninstall.ts"`. Relay stdout. This hard-deletes `feedback/`, `figloops.config.json`, all `figloops.config.*.json.bak`, and strips `FIGMA_TOKEN`/`FIGLOOPS_PLUGIN_DIR` from `.env` (deletes `.env` if empty after). Figma file untouched. Then continue with this wizard from Step 3 — skip Step 2b entirely (config is gone).
- Cancel: print `"Cancelled. Existing round preserved."` Abort.

**2b. `figloops.config.json`** — if present, try to validate with an existing token. Check `process.env.FIGMA_TOKEN` then `.env` file for a `FIGMA_TOKEN=` line.

If a token is available, run:
```bash
"<PLUGIN_DIR>/node_modules/.bin/tsx" "<PLUGIN_DIR>/scripts/validate-file.ts" "<KEY_FROM_CONFIG>"
```

Three branches:

- **Validation succeeds:**
  ```
  question: "Existing figloops.config.json found and Figma file validates. Reuse it?"
  header: "Existing config"
  options:
    - label: "Reuse — skip wizard, re-init state only"
    - label: "Walk through wizard — current values become defaults"
    - label: "Start fresh — archive old config and re-collect everything"
  ```
  - Reuse: skip to step 10 (Initialize state). Steps 3–9 are unnecessary.
  - Walk through wizard: continue normally; pre-fill answers in steps 5–7 from existing config where options are presented.
  - Start fresh: rename `figloops.config.json` to `figloops.config.<YYYYMMDD-HHMMSS>.json.bak`. Continue.

- **Validation fails (401/403/404 or network):** tell user `"Existing figloops.config.json points to a Figma file that isn't accessible (fileKey: <KEY>, error: <msg>)."` Then:
  ```
  question: "How do you want to handle the stale config?"
  header: "Stale config"
  options:
    - label: "Archive it and start fresh"
    - label: "Keep it (I'll fix the fileKey manually) — abort init"
  ```
  - Archive: rename to `.bak`. Continue.
  - Keep it: abort with a one-line summary of what to fix.

- **No token available:** print `"Existing figloops.config.json found, but no FIGMA_TOKEN is set so it can't be validated yet."` Then:
  ```
  question: "What do you want to do with the existing config?"
  header: "Existing config"
  options:
    - label: "Reuse it — skip wizard, re-init state only"
    - label: "Start fresh — archive and re-collect everything"
  ```
  - Reuse: skip to step 10.
  - Start fresh: archive + continue.

If neither file exists, skip this step entirely.

### Step 3 — Setup checklist

Create 5 tasks in a single message (all `pending`):
- `[FIGLOOPS] Verify Figma MCP`
- `[FIGLOOPS] Authenticate with Figma`
- `[FIGLOOPS] Connect Figma file`

From tyburrowbridge/figloops, MIT.

More from tyburrowbridge/figloops