vinta-schedule-frontend-web

Add a Playwright end-to-end spec to the existing `e2e/` suite in vinta-schedule-frontend-web — pick the next free PR###/PA### id, append the row to QA_USE_CASES.md, add a page object under e2e/page-objects/, and write the spec at e2e/tests/app/<ID>-<slug>.spec.ts using the memberPage / adminPage auth fixtures. Use when the user says "add an e2e test", "cover this flow end-to-end", "write a Playwright spec", "add a QA use-case with a test", or when a plan phase's Tests → E2E line names a spec that doesn't exist yet. NOT for unit or component tests (Vitest + Testing Library, colocated `*.test.tsx`).

Introduce a new environment variable in vinta-schedule-frontend-web and propagate it through every layer that must know about it — `.env.example`, the reader module, the `NEXT_PUBLIC_` decision, Vercel's environment settings, the deploy workflow, `playwright.config.ts`'s webServer env forwarding, and the AGENTS.md env section. Use when the user says "add an env var", "make X configurable", "read Y from the environment", "add a feature flag via env", or when a plan phase introduces a new config value. NOT for changing an existing var's value (that's a Vercel dashboard / local `.env` edit, no code change).

Add or update a colocated Storybook story (*.stories.tsx) for a component, following this repo's @storybook/nextjs-vite conventions (meta/StoryObj, viewports, themes, fullscreen). Use when the user says "add a story", "put X in Storybook", "document this component in Storybook", "add a Storybook example", or after creating/changing a visual component. NOT for non-visual logic.

Adjust an existing implementation plan in `ai-plans/` after implementation has started or finished. Updates the plan file (revising existing phases or appending new ones), then for each affected phase that was already implemented adjusts its commits (`git commit --amend` or new commits) on the phase branch, force-pushes the rewritten branch, rebases every downstream stacked phase branch, force-pushes each, and refreshes the PR-context files. Use when the user says "amend the plan", "update phase N", "add a phase to plan X", "the spec changed, fix the plan", or "rewrite the implementation for phase N". NOT for one-off changes to a single file unrelated to a plan; use the regular implement skill for that. Agents push branches and open PRs via `gh` after review passes.

Bootstrap a project's `QA_USE_CASES.md` from scratch using the canonical pattern (immutable PA###/PR### ids, role table, per-app numbered sections with role-tagged checklists). Invoked from inside [plan-feature](../plan-feature/SKILL.md) when the project has no `QA_USE_CASES.md` yet — the active feature's spec + plan are already in hand. Seeds the file with use cases from those two documents only; does not sweep prior plans. Asks the user for the few gaps spec/plan don't answer (app boundaries, role list, prefix conventions). Project-agnostic — works in any repo that adopts this skill set.

Internal execution step of [implement-plan] / [amend-plan] — NOT a standalone entry point. Given one already-classified plan phase plus the resolved `WORKROOT` / `BASE_BRANCH` / `SANDBOX_TIER`, it composes a token-efficient implementer prompt, picks the model from the phase's own suggestion, and spawns exactly one implementer subagent, returning that agent's report. Do not invoke directly for ad-hoc edits or in response to a user's raw feature request; the conductor invokes it once per executable phase in vinta-schedule-frontend-web.

Execute a phased implementation plan from `ai-plans/` in vinta-schedule-frontend-web by orchestrating one subagent per phase (using whatever model the plan suggests and the runtime supports), pushing branches to GitHub per the run's resolved commit strategy (stacked branch + PR per phase, or one plan branch + PR with atomic commits — asked at Step 0), and tracking progress. Use when the user says "implement the plan", "execute plan X", "start implementation", "run phase N of plan Y", "implement {feature} plan", or asks to drive a `*_IMPLEMENTATION_PLAN.md` file phase-by-phase. NOT for one-off changes, single-file edits, or work that doesn't have an existing plan. Agents push branches and open PRs via `gh` after review passes.

Internal integration step of [implement-plan] — NOT a standalone entry point. The **modular-commits** variant, dispatched when `run_options.commit_strategy_resolved = modular-commits`. Pushes one reviewed phase's atomic commits to the shared plan branch (`plan/{plan-id-kebab}`) and opens (or updates) the single plan-level PR through the prs-context file + bundled open-pr.sh — the only PR-creation path. The conductor passes the resolved `WORKROOT` / `BASE_BRANCH` and the PR / inline-comment policy; do not invoke directly to push arbitrary work.

Internal integration step of [implement-plan] — NOT a standalone entry point. The **stacked-branches** variant, dispatched when `run_options.commit_strategy_resolved = stacked-branches`. Pushes one reviewed phase to its own stacked branch (`plan/{plan-id-kebab}/phase-{id}`, based on the previous phase) and opens its PR through the prs-context file + bundled open-pr.sh — the only PR-creation path. The conductor passes the resolved `WORKROOT` / `BASE_BRANCH` and the PR / inline-comment policy; do not invoke directly to push arbitrary work.

Scaffold a new atom — either a shadcn/ui component (cva variants, src/components/ui/) or a layout primitive (token-prop driven, src/components/layout/). Use when the user says "create an atom", "new UI component", "add a Button/Badge-like component", "add a layout primitive", or "create a reusable <thing> component". NOT for feature views composed of other components (use new-composition) or full routes (use new-page).

Scaffold a feature composition — a component assembled from layout primitives + ui atoms under src/components/<feature>/, like a form, card view, navbar, or section. Use when the user says "build a <feature> component", "create a form for X", "add a settings panel/section", "make a <thing> view", or assembles existing atoms into something larger. NOT for design-system atoms (use new-component) or full routes (use new-page).

Scaffold a new data hook that wraps a generated TanStack Query operation, following this repo's src/hooks/<domain>/ convention. Use when the user says "add a hook", "create a useX hook", "wire up the <endpoint> API", "fetch <resource> with a hook", or "add a mutation/query for <thing>". NOT for non-data React hooks unrelated to the API (write those inline or ask).

Scaffold a new Next.js App Router page (route) in this repo following its server-first conventions. Use when the user says "create a page", "add a route", "new screen at /x", "make a /settings page", or asks to add any URL-addressable view under src/app/. NOT for non-route components (use new-composition) or design-system atoms (use new-component).

Author a phased implementation plan for a new feature following the repo's `ai-plans/` conventions. Use when the user asks to "plan", "design", "scope", or "break down" a feature, write an implementation plan / IMPLEMENTATION_PLAN.md, or turn a spec/idea into a phased roadmap. Always interrogates the requester before drafting.

Provision a fully-runnable git worktree for parallel feature work so a long-running plan (or experiment) can build, test, lint, run migrations, and hit databases without disturbing the main checkout — or other parallel worktrees. Reads the active plan (when given one) plus the project's `.gitignore`, package manifests, env templates, and docker config to decide what to symlink, what to copy, what to fork (DBs, env files, compose project names, test databases, sandboxes). Use when the user says "set up a worktree for plan X", "create an isolated env for this feature", "I want to run two plans in parallel without breaking the main checkout", or when [implement-plan](../implement-plan/SKILL.md) opts in via Step 0 question (c). NOT for one-off branch switches that don't need a separate runnable copy of the app.

Internal review gate of [implement-plan] / [amend-plan] / [systematic-debugging] — NOT a standalone entry point. Runs the mandatory three-layer review (mechanical checks, plan-compliance walkthrough, independent reviewer subagent) plus the fix loop against one phase's diff in vinta-schedule-frontend-web, spawning reviewer + fixer subagents and looping until all three layers are clean. The invoking conductor passes the diff, the phase body to walk against, and the resolved `WORKROOT`; do not invoke directly to "review my code" — use the project's standard code-review path for that.

Use when debugging any defect, test failure, regression, performance issue, or unexpected behavior in vinta-schedule-frontend-web (Next.js 16 App Router + React 19 + TypeScript strict; Tailwind v4 with tokens in the `vinta-schedule-design-system` pnpm-workspace package (shadcn/ui atoms + layout primitives); TanStack Query v5 over hey-api generated OpenAPI clients; react-hook-form + zod; Vitest + Testing Library; Playwright e2e; two Storybooks; deployed to Vercel via tag-driven CI). Enforces a root-cause-first investigation flow before any code change is proposed. Pulls evidence from the project's observability MCP tools (sentry) before forming a hypothesis. Cites the project's real test, lint, and type-check commands so reproduction steps are concrete.

Run an extremely strict maintainability review of a diff — abstraction quality, giant files, and spaghetti-condition growth. This is a deep, on-demand structural audit, harsher than the normal per-phase review: it hunts for "code judo" reframes that make whole branches, helpers, modes, or layers disappear rather than polishing what's there. Use when the user asks for a "thermo-nuclear code quality review", "thermonuclear review", "deep code quality audit", or "harsh maintainability review", or when the standard review flow escalates a structural concern. Opt-in only — do not auto-run it on every diff; it is meant to be invoked deliberately. Read-only: it reports findings and hands each fix to a fixer, it does not edit code itself.