docs(ai): bootstrap AI Week artifacts (L1-L3)

.agents/commands/sdd-full-bootstrap.md

@@ -0,0 +1,65 @@
+# SDD Full Bootstrap — pickup-points-modal
+
+Use this command when starting a **new feature** on this repo that requires the Full SDD flow.
+
+## When to use Full SDD
+
+- Any new user-facing feature or behavioral change in `react/`.
+- Changes to the public component API (`PickupPointsModal.js` props, events, `orderForm` shape).
+- Changes that touch `manifest.json`, `package.json`, or CI pipelines.
+- All work on `main`-targeted branches (not hotfix branches).
+
+**Lite-only is allowed** for hotfixes on `fix/*` or `chk-*` branches. See `sdd-lite-bootstrap.md`.
+
+## Pipeline
+
+```
+/speckit-specify   → generates specs/<feature>/spec.md
+/speckit-plan      → generates specs/<feature>/plan.md
+/speckit-tasks     → generates specs/<feature>/tasks.md
+/speckit-implement → executes tasks in code
+/speckit-analyze   → audits consistency between spec/plan/tasks/code
+```
+
+Or use the higher-level skill aliases:
+
+```
+/specification  → Business Context + Arch Decisions + Technical Contract (spec.md)
+/implementing   → Implement from an approved spec up to the PR
+```
+
+## Before starting
+
+1. Read `AGENTS.md` — verified commands, autonomy limits, sources of truth.
+2. Read `.specify/memory/constitution.md` — binding principles.
+3. Confirm the Jira/GitHub issue exists and acceptance criteria are clear.
+4. Run `yarn install` from repo root.
+
+## Verified commands
+
+```bash
+yarn lint          # ESLint over js,jsx,ts,tsx
+yarn lint:ts       # tsc --noEmit
+yarn lint:locales  # intl-equalizer (i18n key parity)
+yarn test          # Jest on react/
+yarn test:coverage # Jest with coverage report
+yarn build         # Production build (lib/ + locales)
+```
+
+## Files that require human approval before touching
+
+- `manifest.json` — version, dependencies, builders.
+- `package.json` — dependencies, scripts, engines.
+- `react/PickupPointsModal.js` — root component (public API).
+- `react/ModalState.js` — root state manager.
+- `.travis.yml`, `.github/**`, `.vtex/deployment.yaml` — CI/CD.
+- `CHANGELOG.md` bumps and `vtex publish` / `npm publish`.
+
+## Quality gates before opening PR
+
+- [ ] `yarn lint` passes (0 errors).
+- [ ] `yarn lint:ts` passes (0 type errors).
+- [ ] `yarn lint:locales` passes (all locale files in sync).
+- [ ] `yarn test` passes (all existing tests green).
+- [ ] New behavior covered by at least one Jest test.
+- [ ] `spec.md` approved before implementation starts.

.agents/commands/sdd-lite-bootstrap.md

@@ -0,0 +1,49 @@
+# SDD Lite Bootstrap — pickup-points-modal
+
+Use this command for **hotfixes** on `fix/*` or `chk-*` branches where Full SDD would be excessive overhead.
+
+## When Lite is allowed
+
+- Bug fixes with a clear, contained scope (no public API change).
+- Branch name starts with `fix/` or `chk-`.
+- Change touches fewer than 3 files in `react/components/` or `react/utils/`.
+- No changes to `manifest.json`, root components, or CI.
+
+For everything else, use the Full SDD flow (`sdd-full-bootstrap.md`).
+
+## Pipeline
+
+```
+/specification  → creates a lightweight spec.md (Business Context + Technical Contract)
+/implementing   → implements from the approved spec up to the PR
+```
+
+## Before starting
+
+1. Read `AGENTS.md` — verified commands, autonomy limits, sources of truth.
+2. Confirm the bug is reproducible and the fix scope is clear.
+3. Run `yarn install` from repo root.
+
+## Verified commands
+
+```bash
+yarn lint          # ESLint over js,jsx,ts,tsx
+yarn lint:ts       # tsc --noEmit
+yarn lint:locales  # intl-equalizer (i18n key parity)
+yarn test          # Jest on react/
+yarn test:coverage # Jest with coverage report
+```
+
+## Files that require human approval even on hotfix branches
+
+- `manifest.json` — version bump.
+- `react/PickupPointsModal.js` — public API surface.
+- `react/ModalState.js` — root state manager.
+- `.travis.yml`, `.github/**` — CI/CD.
+
+## Quality gates before opening PR
+
+- [ ] `yarn lint` passes (0 errors).
+- [ ] `yarn lint:ts` passes (0 type errors).
+- [ ] `yarn test` passes (all tests green).
+- [ ] Reproducing test added (failing before fix, green after).

.agents/rules/00-baseline.md

@@ -0,0 +1,61 @@
+---
+name: pickup-points-modal-baseline
+description: Baseline rules every agent must follow when editing this repo.
+applyTo: "**/*"
+---
+
+# Baseline Rules — pickup-points-modal
+
+## Stack
+
+- **App:** `vtex.pickup-points-modal` — VTEX IO React component for checkout.
+- **Source:** `react/` (no `node/` builder). Legacy JS + TypeScript coexist.
+- **Test runner:** Jest via `vtex-test-tools` (`yarn test` from repo root).
+- **Linter:** ESLint with `eslint-config-vtex` (root) and `eslint-config-vtex-react` (`react/`).
+- **Formatter:** Prettier with `@vtex/prettier-config`.
+- **Type checker:** `tsc --noEmit -p react/tsconfig.json`.
+
+## Verified commands (always run from repo root)
+
+```bash
+yarn install          # install all dependencies first
+yarn lint             # ESLint — must pass before any PR
+yarn lint:ts          # TypeScript check — must pass before any PR
+yarn lint:locales     # i18n key parity check — must pass before any PR
+yarn test             # Jest test suite — must pass before any PR
+yarn test:coverage    # Jest with coverage
+yarn format           # Prettier auto-fix
+yarn build            # production build
+```
+
+## Autonomy limits
+
+**May modify freely:**
+- `react/components/`, `react/containers/`, `react/utils/`, `react/fetchers/`, `react/types/`
+- Tests: `react/**/__tests__/`, `react/**/*.test.{js,ts,tsx}`
+- Messages: `messages/` — add keys to ALL locale files in the same PR
+
+**Must ask for human approval:**
+- `manifest.json` (version, dependencies, builders)
+- `package.json` (dependencies, scripts, engines)
+- `.travis.yml`, `.github/**`, `.vtex/deployment.yaml` (CI/CD)
+- `react/PickupPointsModal.js` or `react/ModalState.js` (root/public API)
+- Any publish action: `vtex publish`, `npm publish`, `CHANGELOG.md` bump
+
+**Must never:**
+- Run `git push --force` on `main` or skip hooks with `--no-verify`
+- Commit secrets, `.env*` files, or Google Maps keys
+- Remove tests to unblock a build
+- Mock `orderForm` in integration tests — use `react/__mocks__/` fixtures
+
+## SDD flow
+
+- **Default:** Full SDD for all features (see `.agents/commands/sdd-full-bootstrap.md`)
+- **Lite-only:** hotfixes on `fix/*` or `chk-*` branches (see `.agents/commands/sdd-lite-bootstrap.md`)
+
+## Sources of truth (priority order)
+
+1. `.specify/memory/constitution.md` — binding principles
+2. `README.md` — public API and props
+3. `CONTRIBUTING.md` — PR flow and changelog rules
+4. `manifest.json` — published version and VTEX IO dependencies

.agents/rules/10-react.md

@@ -0,0 +1,43 @@
+---
+name: pickup-points-modal-react
+description: Rules scoped to the React source in react/ — component conventions, testing, i18n, and public API gate.
+applyTo: "react/**/*"
+---
+
+# React Source Rules — pickup-points-modal
+
+## Component conventions
+
+- **Class components** are legacy — prefer functional components with hooks for new code.
+- **PropTypes** are required on all new components alongside TypeScript types (dual-declaration pattern already used in the codebase).
+- Container components live in `react/containers/`; pure UI in `react/components/`.
+- Side effects and I/O belong in `react/fetchers/` or `react/containers/`, never inside utility functions in `react/utils/`.
+- Utility functions must be pure (no I/O, no singletons). Name I/O functions explicitly: `fetchX`, `saveY`, or suffix with `Event` for telemetry (see `react/utils/metrics.js`).
+
+## Testing expectations
+
+- Test files live in `react/**/__tests__/` or next to source as `*.test.{js,ts,tsx}`.
+- Every behavioral change must be accompanied by at least one Jest test covering the new behavior.
+- Use `react/__mocks__/` fixtures for `orderForm` and VTEX IO module mocks — do not create new inline mocks for these.
+- Snapshot tests (`.snap`) are in `react/components/__tests__/__snapshots__/` — update them intentionally, never blindly.
+
+## Internationalization (non-negotiable)
+
+- Every user-facing string must use `react-intl` (`<FormattedMessage>` or `intl.formatMessage`).
+- New i18n keys must be added to **all** locale files in `messages/` in the same PR.
+- `messages/context.json` is the English master — new keys go here first.
+- Run `yarn lint:locales` before opening any PR that touches `messages/`.
+
+## Public API gate
+
+`react/PickupPointsModal.js` is the public contract consumed by production VTEX stores.
+
+- Any prop addition, removal, or shape change is **breaking** and requires a major version bump in `manifest.json`.
+- Changes to this file require human approval and an explicit `CHANGELOG.md` entry.
+- The Google Maps gated load in `react/containers/withGoogleMaps.js` must not be bypassed.
+
+## Performance rules
+
+- No unconditional network requests on initial render without cache or debounce.
+- No heavy library imports in the main bundle without justification in the PR description.
+- PRs that increase bundle size must explain the cost and loading strategy.

.agents/skills/implementing/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: implementing
+description: Implement an approved spec end-to-end in the pickup-points-modal repo — branch, code, tests, lint, typecheck, build, commit, and open a PR following Conventional Commits and the project constitution.
+type: skill
+---
+
+# implementing
+
+Use this skill when the user says "implement it", "implement this spec",
+"implement specs/<feature>.md", or asks for autonomous execution from an
+already-approved spec.
+
+## Prerequisites
+
+- `specs/<feature>/spec.md` exists and is approved by the user.
+- Constitution has been read
+  ([.specify/memory/constitution.md](../../../.specify/memory/constitution.md)).
+- AGENTS.md has been read for autonomy limits.
+
+If any of these is missing, **stop** and ask the user to run the
+`specification` skill first.
+
+## Flow
+
+1. **Branch.** `git checkout -b feat/<feature-slug>` (use `fix/<slug>`
+   for bug fixes, `chore/<slug>` for tooling).
+2. **Break into tasks.** List 3–8 concrete tasks in TodoWrite.
+3. **Implement task by task.**
+   - For each task: edit files → run `yarn lint --fix` → run
+     `yarn test` in the affected scope → mark task complete.
+   - Never skip tests. Principle 2 of the constitution.
+4. **Lint & types.** Run `yarn lint` and `yarn lint:ts` before
+   committing.
+5. **i18n.** If a visible string was added, run `yarn lint:locales`.
+   Principle 3 of the constitution.
+6. **Build.** `yarn build` must pass.
+7. **Commit.** Use `speckit-git-commit` to format Conventional Commits.
+8. **PR.** Open with `gh pr create`, linking the spec, principles
+   affected, and manual test plan.
+
+## Autonomy limits
+
+See [AGENTS.md](../../../AGENTS.md). In short:
+
+- **Do not touch** `manifest.json`, `package.json`, `.travis.yml`,
+  `.github/`, `.vtex/deployment.yaml` without explicit confirmation.
+- **Do not publish.** `vtex publish` and `npm publish` are manual.
+- **Do not force-push** to a branch that already has an open PR.
+
+## When to pause and report
+
+Pause and report back to the user when:
+
+- The build fails in a way that suggests a dependency range change.
+- Typecheck flags an issue in code you did not touch.
+- A product/UX decision is not covered by the spec.

.agents/skills/specification/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: specification
+description: Generate an SDD (Spec Driven Development) document for a new feature in the pickup-points-modal, covering Business Context, Architectural Decisions, and Technical Contract before any code is written.
+type: skill
+---
+
+# specification
+
+Use this skill when the user asks to "create a spec", "write an SDD", or
+references a file under `specs/`. The deliverable is a
+`specs/<feature-slug>/spec.md` file with three mandatory sections.
+
+## When to use
+
+- New feature that touches the public contract of `PickupPointsModal`.
+- Architectural change (new container, new state flow).
+- Refactor with cross-cutting impact (i18n, fetchers, map).
+
+**Do not use** for a one-off bug fix or a styling tweak — go straight to
+`implementing` or `speckit-git-commit`.
+
+## Deliverable structure
+
+```markdown
+# Spec: <feature>
+
+## Business Context
+- Problem being solved
+- Stakeholders (who asked, who is impacted)
+- Success metrics
+
+## Architectural Decisions
+- Components/files affected
+- Alternatives considered + why they were dropped
+- Backward-compatibility risk (cite Principle 1 of the constitution)
+
+## Technical Contract
+- Changes to props/events
+- Changes to fixtures/mocks
+- Test plan (golden path + edge cases)
+- i18n plan (new keys, locales touched)
+- Verifiable acceptance criteria
+```
+
+## Expected inputs
+
+- Natural-language description of the feature.
+- Link to a Jira/issue ticket if one exists.
+- List of suspected files (if the user has already investigated).
+
+## How to apply
+
+1. Read [.specify/memory/constitution.md](../../../.specify/memory/constitution.md)
+   to understand binding principles.
+2. Read [AGENTS.md](../../../AGENTS.md) for autonomy limits.
+3. Sketch the 3 sections with `TBD` markers where input is missing.
+4. Present the draft to the user before creating the final file.
+5. Do not implement anything — spec only.

.agents/skills/speckit-analyze/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: speckit-analyze
+description: Audit consistency between spec.md, plan.md, tasks.md, and the actual code in the pickup-points-modal — flagging drift, missing tasks, or out-of-spec changes before PR review.
+type: skill
+---
+
+# speckit-analyze
+
+Lightweight audit before opening the PR. Detects drift across the four
+artifacts: spec → plan → tasks → code.
+
+## When to use
+
+- After `speckit-implement` and before `gh pr create`.
+- When the spec author is different from the implementer.
+- Before requesting human review on a large feature.
+
+## Checks
+
+1. **Spec → Plan:** does every acceptance criterion from the spec
+   appear as an item in the plan?
+2. **Plan → Tasks:** does every file listed under "Files to touch"
+   have at least one task?
+3. **Tasks → Code:** is every file modified in `git diff` covered by
+   some task?
+4. **Constitution check:** does the diff respect the 5 principles?
+
+## Output
+
+A markdown report listing:
+
+- ✅ Items in sync
+- ⚠️ Drift (changed in code but not in the task/spec)
+- ❌ Missing (acceptance criterion without implementation)
+
+It does not fix anything — it only reports. The user decides whether to
+update spec/plan or revert the code.
+
+## Important
+
+`speckit-analyze` is **read-only**. It never edits the spec, plan,
+tasks or code. If drift is found, it returns the report and stops.