---
name: spreadsheet-ai-plan
description: Resume or continue the spreadsheet-ai Tabular Review demo (Laravel 13 + React/Vite/Tailwind + Glide Data Grid + laravel/ai). Use when working in the spreadsheet-ai repo, when context was lost, when following the saved plan, or when enforcing the branch/PR/Copilot-review/testing/security/UI rules for this project.
---

# spreadsheet-ai — resume skill

You are building a **functioning single-page demo of an agentic spreadsheet**
("Tabular Review"): rows = e-commerce entities, columns = LLM prompts, cells =
AI values with confidence flag + citation. Stack: Laravel 13 + SQLite +
`laravel/ai`, React 19 + Vite + Tailwind v4 + Glide Data Grid, synchronous SSE,
Mock-default + Live LLM toggle.

## Start here (read in order, every time)
1. `AGENTS.md` — operating instructions + the branch/PR/Copilot loop.
2. `docs/plan.md` — canonical plan, deep analysis (§1), task breakdown (§3, M0–M7).
3. `docs/PROGRESS.md` — where the last session stopped; resume from the top.
4. `docs/LESSON.md` — non-obvious facts/fixes (incl. `laravel/ai` option-forwarding gotcha, extractor upsert race, prototype renderer bugs).
5. `docs/RULES.md` — binding implementation/security/testing/review/UI rules.

## External references (read, don't re-derive)
- Article: `%USERPROFILE%\Downloads\medium\SpreadsheetAi\article-bozza-italiano.md`
- Design prototype (pixel reference + presets + 17 renderers + CSS tokens): `%USERPROFILE%\Downloads\SpreadsheetAi\tabular-review-demo\project\`
- Backend patterns to copy: `%USERPROFILE%\Documents\DocLore\Visual Basic\Ai\AskMyDocs`
- Governance template: `%USERPROFILE%\Documents\DocLore\Visual Basic\Ai\product_image_discovery_admin`
- Screenshots for README: `resources/Tabular-Review-Banner.png`, `…-Ai-suggested.png`, `…-Prompt-Column.png`

## Procedure
1. Read current state (above). Scope to the current macro task / subtask from `docs/plan.md` §3.
2. Implement on a branch (`task/m{N}-{slug}`); subtasks PR into the macro branch.
3. Define guardrails as tests up front: PHPUnit (backend), Vitest (frontend), and Playwright scenarios for **every** UI/UX interaction.
4. Definition of Done — canonical 7-step version in `docs/plan.md §2`; summary here:
   a. **Define guardrails as tests** up front before implementation.
   b. **Local tests** green (phpunit, vitest, vite build, Playwright for UI).
   c. **Local Copilot review** (before push): see `AGENTS.md §Local Copilot review` for the exact command. Fix + re-run + loop until clean.
   d. Push → open PR → request **GitHub Copilot** review via REST `gh api --method POST repos/<owner>/<repo>/pulls/<PR>/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'` (confirm via `reviewRequests`).
   e. **MANDATORY — never merge early**: wait for **GitHub Actions CI green** AND a **posted Copilot review with zero open comments**. Poll for minutes if needed. CI red or Copilot comments → fix, push, re-request, loop.
   f. Merge ONLY when CI green AND Copilot zero open comments. Record findings in `docs/LESSON.md`; update `docs/PROGRESS.md`.
5. After each meaningful step: update `docs/PROGRESS.md`. On any non-obvious learning (incl. Copilot feedback): update `docs/LESSON.md`.

## Macro task order
M0 governance (done first) → M1 Laravel foundation + DB + seeders + ai config →
M2 backend engine (FormatType, extractor, json_path, SSE) → M3 frontend shell →
M4 Glide grid + 17 renderers + SSE consumer → M5 column editor + AI Suggest +
bulk + citation panel → M6 presets/workflows/polish/export → M7 CI + WOW README +
knowledge consolidation + tag `v0.1.0` & GitHub release.

## Hard rules (quick)
- Controllers use `config()`, never `env()`. Never leak provider errors/secrets.
- Atomic cell upsert keyed `(review_id,row_id,column_index)`; encode JSON with `JSON_THROW_ON_ERROR | JSON_INVALID_UTF8_SUBSTITUTE`, degrade to red on failure.
- `url` cells: `http:`/`https:` only. CSV export: neutralize `= + - @`.
- Windows/Herd PHP 8.4 (satisfies `^8.3`), not XAMPP; phpunit via `npm run phpunit` wrapper. Vitest `pool: threads`.
- Final task: fold `docs/LESSON.md` into rules/skills/AGENTS.md/CLAUDE.md before tagging the release.