projecta-rrr 1.7.0 → 1.9.1

package/README.md

@@ -84,6 +84,57 @@ That's it. Verify with `/rrr:help` inside your Claude Code interface.
 >
 > This resolves "Unknown skill: rrr:help" errors.
 
+### Where to Run Commands
+
+| Environment | What to run | Notes |
+|-------------|-------------|-------|
+| **Inside Claude Code** | `/rrr:*` slash commands | Interactive planning/execution |
+| **Outside Claude Code** | `bash scripts/pushpa-mode.sh` | Unattended overnight runs |
+| **npm scripts** | `npm run pushpa`, `npm run e2e` | Convenience wrappers |
+
+**After installing from inside Claude Code:** Exit and restart `claude` to load new commands.
+
+**Pushpa Mode (overnight):** Always run in a separate terminal window for true unattended execution. The script detects if running inside Claude Code and prompts you to confirm or exit.
+
+### Quick Start by Scenario
+
+| Your situation | Command to run |
+|----------------|----------------|
+| **Empty folder** (greenfield) | `/rrr:new-project` — bootstraps Next.js/TS + full planning |
+| **Existing repo** (brownfield) | `/rrr:map-codebase` (optional) → `/rrr:new-project` |
+| **Already initialized** (has `.planning/STATE.md`) | `/rrr:progress` |
+| **Not sure which?** | `/rrr:mvp` — detects state and routes you |
+
+**MVP Definition of Done at Projecta:** local demo runs + tests pass.
+
+### Pushpa Mode (Overnight Autopilot)
+
+Run phases unattended while you sleep. **Best run in a normal terminal** (outside Claude Code):
+
+```bash
+bash scripts/pushpa-mode.sh
+# or
+npm run pushpa
+```
+
+> **Where to run:** A system terminal or VS Code integrated terminal works great. Running inside the Claude interactive session can trigger approval prompts. The script detects this and prompts you to confirm or exit.
+
+**Quick guidance:** `/rrr:overnight` — checks prerequisites and gives exact instructions.
+
+**Outputs:**
+- Report: `.planning/PUSHPA_REPORT.md`
+- Logs: `.planning/logs/pushpa_*.log`
+- Artifacts: `.planning/artifacts/playwright/`
+
+**Optional:** Add to your project's `package.json`:
+```json
+{
+  "scripts": {
+    "pushpa": "bash scripts/pushpa-mode.sh"
+  }
+}
+```
+
 ### Staying Updated
 
 RRR evolves fast. Check for updates periodically:
@@ -332,17 +383,80 @@ Pushpa Mode will skip these phases and record them in the report for manual foll
 - Running inside Claude Code works but can trigger approval prompts ("Do you want to proceed?").
 - The script detects if it's running inside Claude Code and prompts: `Continue running Pushpa Mode inside Claude Code? (y/N)` — default is **No**. Press Enter to exit with instructions to run externally.
 
-### Visual Proof (Automated UX Verification)
+### Verification Ladder
+
+RRR uses a deterministic verification ladder with **mandatory two-step verification** for frontend-impacting plans:
+
+**Plan Classification:**
+- **frontend_impact: true** — plans touching frontend files, UI keywords, API routes used by UI, FE integration
+- **frontend_impact: false** — plans with no user-visible impact (scripts, migrations, pure utilities)
+
+**Verification by Frontend Impact:**
+
+| frontend_impact | unit_tests | playwright | browser_uat |
+|-----------------|------------|------------|-------------|
+| true | Yes | Yes | Yes (agent-browse or claude --chrome) |
+| false | Yes | No | No |
+
+**Two-Step Visual Verification (frontend_impact: true):**
+1. **Step 1: Playwright** — Automated headless E2E tests
+2. **Step 2: Browser UAT** — Natural language browser automation via agent-browse (preferred) or `claude --chrome` (fallback)
+
+**Browser UAT Tool Selection:**
+- **ANTHROPIC_API_KEY set + agent-browse plugin:** Uses agent-browse (natural language browser automation via Stagehand)
+- **ANTHROPIC_API_KEY not set + interactive:** Falls back to `claude --chrome`
+- **Pushpa/CI without ANTHROPIC_API_KEY:** Skipped (no automated browser available)
+
+**Installing agent-browse plugin (in Claude Code):**
+```bash
+/plugin marketplace add browserbase/agent-browse
+/plugin install agent-browse@browserbase
+```
+
+Both steps run even when Playwright passes — we want visual/UI confirmation.
+
+The planner automatically classifies plans and adds `verification:` frontmatter:
+```yaml
+verification:
+  surface: ui_affecting
+  frontend_impact: true
+  required_steps:
+    - unit_tests
+    - playwright
+    - browser_uat
+```
+
+### Visual Proof (Mandatory Two-Step Verification)
 
-RRR includes automated visual proof via Playwright tests and UX telemetry capture.
+RRR includes automated visual proof via Playwright tests and browser UAT verification.
 
 **What it captures:**
 - Playwright test results (pass/fail)
+- Browser UAT confirmations (page renders, interactions, layout)
 - Console errors and warnings
 - Page errors (uncaught exceptions)
 - Network failures (4xx, 5xx, failed requests)
 - Screenshots, traces, and videos (on failure)
 
+**Artifacts location:**
+```
+.planning/
+├── VISUAL_PROOF.md                    # Append-only run log (both steps)
+└── artifacts/
+    ├── playwright/
+    │   ├── report/                    # HTML report (index.html)
+    │   │   └── index.html
+    │   └── test-results/              # Per-test artifacts
+    │       ├── screenshot.png         # Captured on failure
+    │       ├── trace.zip              # Recorded trace
+    │       └── video.webm             # Recorded video
+    └── browser-uat/
+        └── {run_id}/                  # Browser UAT artifacts
+            ├── uat.log                # Execution log
+            ├── screenshot-*.png       # Captured screenshots
+            └── chrome-notes.md        # Claude chrome notes (fallback mode)
+```
+
 **Modes** (configured in `.planning/config.json`):
 
 | Mode | Behavior |
@@ -352,25 +466,61 @@ RRR includes automated visual proof via Playwright tests and UX telemetry captur
 | `hybrid` | Headless first, prompt for interactive fallback on eligible failures |
 | `interactive_only` | Skip Playwright, show manual UAT checklist |
 
-**Artifacts location:**
-- Report: `.planning/artifacts/playwright/report/`
-- Test results: `.planning/artifacts/playwright/test-results/`
-- UX telemetry: `.planning/artifacts/ux-telemetry/`
-- Run log: `.planning/VISUAL_PROOF.md` (append-only)
+**Browser UAT Gating** (in `.planning/config.json`):
+```json
+{
+  "visual_proof": {
+    "uat_gate": "non_blocking"  // or "blocking"
+  }
+}
+```
+- `non_blocking` (default): UAT failures logged but don't block execution
+- `blocking`: UAT failures exit with code 1 (for strict enforcement)
 
 **Commands:**
 ```bash
-npm run e2e              # Run Playwright tests
+# Playwright
+npm run e2e              # Run Playwright tests (headless)
 npm run e2e:headed       # Run with browser visible
-npm run e2e:ui           # Playwright UI mode
+npm run e2e:ui           # Playwright UI mode (interactive)
 npm run visual:open      # Open last HTML report
-bash scripts/visual-proof.sh  # Full visual proof runner
+
+# Visual Proof (two-step for frontend_impact: true)
+bash scripts/visual-proof.sh           # Playwright only
+bash scripts/visual-proof.sh --chrome  # Playwright + browser UAT (REQUIRED for FE)
+bash scripts/visual-proof.sh --pushpa  # Pushpa mode (headless)
+
+# Browser UAT directly
+FRONTEND_IMPACT=true bash scripts/browser-uat.sh  # Run browser UAT step
+```
+
+**Browser UAT Tool Selection:**
+- **agent-browse** (preferred): Requires `ANTHROPIC_API_KEY` and [browserbase/agent-browse](https://github.com/browserbase/agent-browse) plugin. Uses Stagehand for natural language browser automation.
+- **claude --chrome** (fallback): Interactive mode only. Falls back when no API key set.
+- **Skipped**: In Pushpa/CI without `ANTHROPIC_API_KEY` (no automated browser available).
+
+**Installing agent-browse (in Claude Code):**
+```bash
+/plugin marketplace add browserbase/agent-browse
+/plugin install agent-browse@browserbase
+```
+
+**Interactive verification (UI_AFFECTING plans only):**
+```bash
+npx playwright test --ui     # Playwright UI mode for exploratory testing
+npx playwright test --headed # See tests execute in browser
+FRONTEND_IMPACT=true bash scripts/browser-uat.sh  # Browser UAT check
 ```
 
 **Integration:**
-- Runs automatically after `/rrr:execute-phase` (if e2e tests exist)
-- Runs in Pushpa Mode (headless only, never interactive)
-- Results logged to `.planning/VISUAL_PROOF.md`
+- **Per-plan:** Runs automatically after `/rrr:execute-plan` when `frontend_impact: true` (Playwright + Browser UAT)
+- **Per-phase:** Runs automatically after `/rrr:execute-phase` (aggregates all plans)
+- **Pushpa Mode:** Headless Playwright + agent-browse (if `ANTHROPIC_API_KEY` set); no interactive fallback
+- **Backend-only plans** (`frontend_impact: false`): Unit tests only, visual steps skipped
+- Results logged to `.planning/VISUAL_PROOF.md` (append-only)
+
+**VISUAL_PROOF.md format:**
+Each run appends an entry with datetime, plan/phase ID, surface type, commands run, pass/fail status, console errors, and artifact paths.
 
 **UX Telemetry Fixture:**
 
@@ -571,6 +721,8 @@ You're never locked in. The system adapts.
 |---------|--------------|
 | `/rrr:progress` | Where am I? What's next? |
 | `/rrr:help` | Show all commands and usage guide |
+| `/rrr:mvp` | Smart router: detects state, tells you exactly what to run |
+| `/rrr:overnight` | Pushpa Mode guidance: preflight checks + run instructions |
 
 ### Verification
 
@@ -615,6 +767,105 @@ You're never locked in. The system adapts.
 | `/rrr:check-todos` | List pending todos |
 | `/rrr:debug [desc]` | Systematic debugging with persistent state |
 
+### Skills
+
+| Command | What it does |
+|---------|--------------|
+| `/rrr:list-skills` | Show all available skills (vendored + community) |
+| `/rrr:install-skill [url]` | Install a skill from GitHub or skillsmp.com |
+| `/rrr:search-skills [query]` | Search for skills on skillsmp.com |
+
+---
+
+## Skills System
+
+Skills are context packages that load into Claude during plan execution. They enforce coding conventions, tool choices, and best practices.
+
+### How Skills Work
+
+1. **Planning** — Planner infers which skills are needed based on phase content
+2. **Execution** — Skills load into executor context (fresh per plan)
+3. **Enforcement** — Claude follows skill rules during implementation
+
+Skills are loaded dynamically per plan. No skill accumulation across plans — keeps context clean.
+
+### Vendored Skills
+
+Ships with RRR:
+
+**Projecta Skills (default stack):**
+- `projecta.nextjs-typescript` ⭐ — Next.js App Router + TypeScript conventions (loads automatically)
+- `projecta.testing` — Vitest + Playwright (NEVER Jest/Cypress)
+- `projecta.visual-proof` — Visual proof artifact capture
+- `projecta.shadcn-ui` — shadcn/ui components (NEVER Material UI/Chakra)
+- `projecta.cloudflare-r2` — Cloudflare R2 storage conventions
+- `projecta.mcp-stack` — MCP server integrations
+
+**Anthropic Skills (vendored from upstream):**
+- `anthropic.pdf` — PDF document handling
+- `anthropic.xlsx` — Excel spreadsheet handling
+- `anthropic.webapp-testing` — Web application testing
+- And 13 more...
+
+### Using Skills in Plans
+
+Skills are auto-inferred from plan content, but you can declare them explicitly:
+
+```yaml
+---
+phase: 04-auth
+plan: 01
+skills:
+  - projecta.testing
+  - projecta.visual-proof
+  - anthropic.webapp-testing
+---
+```
+
+**Default skill:** `projecta.nextjs-typescript` loads automatically for ALL plans. Add `skills_mode: minimal` to skip it (rare, for non-standard stacks).
+
+**Limits:** Max 10 skills per plan, max 1000 total lines.
+
+### Community Skills
+
+Install skills from GitHub or skillsmp.com:
+
+```
+/rrr:install-skill https://github.com/user/repo/blob/main/SKILL.md
+/rrr:search-skills react patterns
+```
+
+Community skills install to `.claude/skills/community/`.
+
+### Vendoring Skills (Maintainers)
+
+RRR uses vendoring scripts to pull skills from external repositories into the `rrr/skills/` directory:
+
+**Anthropic upstream skills** (`scripts/vendor-skills.sh`):
+Vendors official Anthropic skills into `rrr/skills/upstream/anthropic/`.
+
+**Vercel Agent Skills** (`scripts/vendor-vercel-skills.sh`):
+Vendors curated React/Next.js best practices from [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills). Small and included in npm package.
+
+**droid-tings Skills** (`scripts/vendor-droid-tings-skills.sh`):
+Vendors AI/ML focused skills from [ovachiever/droid-tings](https://github.com/ovachiever/droid-tings). Large (~40MB), **not included in npm** to keep package lean. Vendor on-demand when needed.
+
+```bash
+# Vendor Anthropic skills (maintainer use)
+bash scripts/vendor-skills.sh
+
+# Vendor Vercel skills (small, recommended for frontend)
+bash scripts/vendor-vercel-skills.sh
+
+# Vendor droid-tings skills (large, use allowlist)
+bash scripts/vendor-droid-tings-skills.sh --list                    # List available
+DROID_TINGS_ALLOWLIST="axolotl,unsloth" bash scripts/vendor-droid-tings-skills.sh  # Specific skills
+```
+
+**npm Package Policy:**
+- `projecta/*`, `upstream/*`, `community/vercel/*` — included in npm
+- `community/droid-tings/*` — excluded (40MB), vendor locally if needed
+
 ---
 
 ## Troubleshooting

package/agents/rrr-planner.md

@@ -392,6 +392,16 @@ depends_on: []              # Plan IDs this plan requires
 files_modified: []          # Files this plan touches
 autonomous: true            # false if plan has checkpoints
 user_setup: []              # Human-required setup (omit if empty)
+skills: []                  # Skills to load (auto-inferred if empty)
+skills_mode: normal         # "normal" (default) or "minimal" (skip default skill)
+
+verification:
+  surface: ui_affecting     # ui_affecting | backend_only (REQUIRED)
+  frontend_impact: true     # true | false (REQUIRED - enables two-step visual verification)
+  required_steps:           # Steps executor MUST run (auto-derived from surface)
+    - unit_tests
+    - playwright
+    - chrome_visual_check   # Two-step: automated Playwright + claude --chrome
 
 must_haves:
   truths: []                # Observable behaviors
@@ -457,10 +467,179 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `files_modified` | Yes | Files this plan touches |
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `user_setup` | No | Human-required setup items |
+| `skills` | No | Skills to load for execution (auto-inferred if empty) |
+| `skills_mode` | No | `normal` (default) or `minimal` (skip default skill) |
+| `verification.frontend_impact` | Yes | `true` enables two-step visual verification (Playwright + chrome) |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
 **Wave is pre-computed:** Wave numbers are assigned during planning. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number.
 
+## Skills Inference
+
+Skills load into executor context at plan execution time. **Default skill** (`projecta.nextjs-typescript`) loads automatically for ALL plans to ensure consistent stack conventions.
+
+**Inference rules** - when phase content mentions these patterns, include the skill:
+
+| Pattern Keywords | Skill |
+|------------------|-------|
+| test, vitest, playwright, e2e, unit test | `projecta.testing-vitest-playwright` |
+| visual, screenshot, artifact, proof | `projecta.visual-proof` |
+| R2, storage, S3, bucket, upload, cloudflare | `projecta.cloudflare-r2` |
+| PDF, document, pdf | `anthropic.pdf` |
+| spreadsheet, xlsx, excel | `anthropic.xlsx` |
+| MCP, Neon, Stripe, PostHog | `projecta.mcp-stack` |
+| shadcn, tailwind, button, card, dialog, ui component | `projecta.shadcn-ui` |
+| webapp, web app, browser test | `anthropic.webapp-testing` |
+
+**UI/UX Auto-Tagging** - when plan touches UI/UX work, ALWAYS include BOTH skills:
+
+Trigger keywords: `ui`, `ux`, `flow`, `form`, `modal`, `layout`, `preview`, `editor`, `dashboard`, `component`, `page`, `screen`, `view`, `button`, `input`, `navigation`, `menu`, `sidebar`, `header`, `footer`
+
+Trigger file paths (if `files_modified` contains any of these patterns):
+- `src/app/**` or `app/**` (Next.js pages/layouts)
+- `src/components/**` or `components/**`
+- `src/pages/**` or `pages/**`
+- Any `.tsx` file with "page", "layout", "component" in name
+
+When ANY trigger matches, add to frontmatter (deduplicated):
+```yaml
+skills:
+  - projecta.testing-vitest-playwright
+  - projecta.visual-proof
+```
+
+**Important:** Do not duplicate skills in the list. If already explicitly declared, skip.
+
+## Verification Classification (MANDATORY)
+
+Every plan MUST include `verification:` frontmatter. The planner determines `surface` based on classification rules, then derives `required_steps` automatically.
+
+### Classification Rules
+
+**UI_AFFECTING** - plan touches user-visible behavior:
+
+1. **File path patterns** (if `files_modified` matches ANY):
+   - `src/app/**` or `app/**` (Next.js pages/layouts)
+   - `src/components/**` or `components/**`
+   - `src/pages/**` or `pages/**`
+   - `*.tsx` (React components)
+   - `*.css`, `*.scss`, `tailwind.config.*`
+   - `src/styles/**`
+
+2. **Keyword triggers** (in objective, task names, or file content):
+   - UI terms: `ui`, `ux`, `form`, `modal`, `dialog`, `button`, `input`, `layout`
+   - Flow terms: `flow`, `wizard`, `stepper`, `navigation`, `menu`, `sidebar`
+   - Visual terms: `preview`, `editor`, `dashboard`, `chart`, `graph`, `animation`
+   - Page terms: `page`, `screen`, `view`, `component`, `header`, `footer`
+
+3. **API routes used by UI** (patterns in files_modified):
+   - `src/app/api/**` routes that serve UI data
+   - `pages/api/**` routes called from frontend
+
+4. **Schema/types affecting UI** (if plan mentions):
+   - Types used in components
+   - Zod schemas for forms
+   - API response types rendered in UI
+
+5. **Integration mentions**:
+   - "frontend", "client-side", "browser", "user-facing"
+   - "render", "display", "show", "visible"
+
+6. **Backend changes affecting FE integration**:
+   - API routes consumed by FE (app/api, pages/api)
+   - Contracts/DTOs used by FE
+   - Schema changes affecting UI types
+   - Auth/session flow changes
+   - CORS, cookies, redirects
+   - Webhooks displayed in UI
+   - Keywords: "integration", "wiring", "connect frontend", "hook up", "end-to-end"
+
+**Reference:** @~/.claude/rrr/references/frontend-impact-detection.md
+
+**BACKEND_ONLY** - plan has NO user-visible impact:
+
+1. **File path patterns** (ONLY these, no UI files):
+   - `src/lib/**` (pure utilities, no UI)
+   - `src/server/**` (server-only code)
+   - `scripts/**` (CLI/build scripts)
+   - `*.config.*` (configuration files)
+   - Database migrations, seeds
+
+2. **Keyword indicators**:
+   - "migration", "seed", "script", "cli", "cron", "job"
+   - "refactor internals", "optimize query", "add logging"
+   - No UI/visual keywords present
+
+3. **Explicit backend work**:
+   - Database schema changes (not affecting UI types)
+   - Server-side utilities
+   - Build/deploy configuration
+
+### Required Steps by Surface
+
+**UI_AFFECTING plans:**
+```yaml
+verification:
+  surface: ui_affecting
+  frontend_impact: true
+  required_steps:
+    - unit_tests
+    - playwright
+    - chrome_visual_check
+```
+
+**BACKEND_ONLY plans:**
+```yaml
+verification:
+  surface: backend_only
+  frontend_impact: false
+  required_steps:
+    - unit_tests
+```
+
+### Classification Decision Tree
+
+```
+START
+  │
+  ├─ Does files_modified contain ANY .tsx file?
+  │   └─ YES → UI_AFFECTING
+  │
+  ├─ Does files_modified contain src/app/**, src/components/**, src/pages/**?
+  │   └─ YES → UI_AFFECTING
+  │
+  ├─ Does objective/tasks mention UI keywords?
+  │   └─ YES → UI_AFFECTING
+  │
+  ├─ Is this an API route? Check if called from UI
+  │   ├─ Called from frontend → UI_AFFECTING
+  │   └─ Backend-only (cron, webhook) → BACKEND_ONLY
+  │
+  └─ None of the above → BACKEND_ONLY
+```
+
+### When in Doubt
+
+If classification is ambiguous, default to **UI_AFFECTING**. False positives (extra visual checks) are preferable to false negatives (missing UI verification).
+
+**Explicit declaration** (when known):
+```yaml
+skills:
+  - projecta.testing
+  - projecta.visual-proof
+  - anthropic.webapp-testing
+```
+
+**Skip default skill** (rare, for non-standard stacks):
+```yaml
+skills_mode: minimal
+```
+
+**Limits:**
+- Max 10 skills per plan
+- Max 1000 total lines
+- Skills exceeding limits are skipped with warning
+
 ## Context Section Rules
 
 Only include prior plan SUMMARY references if genuinely needed: