@reservine/dx 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "reservine-dx",
+  "version": "1.0.0",
+  "description": "Shared developer experience skills for the Reservine ecosystem (FE + BE)",
+  "owner": {
+    "name": "Reservine",
+    "url": "https://github.com/Reservine/Reservine-DX"
+  },
+  "plugins": [
+    {
+      "name": "reservine-dx",
+      "description": "Cross-repo skills for feature planning, implementation, cherry-pick PRs, worktree setup, and commits across Reservine frontend (Angular) and backend (Laravel).",
+      "version": "1.0.0",
+      "author": { "name": "Reservine" },
+      "source": "./plugins/reservine-dx",
+      "category": "development",
+      "commands": ["./commands/"],
+      "skills": ["./skills/"]
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,303 @@
+# Reservine-DX
+
+Shared developer experience skills for the Reservine ecosystem (Angular frontend + Laravel backend).
+
+A Claude Code marketplace plugin providing cross-repo skills for feature planning, implementation, cherry-pick PRs, worktree setup, and commits.
+
+## Quick Start
+
+```bash
+bunx @reservine/dx install
+```
+
+That's it. Restart Claude Code and the skills are available in any Reservine repo.
+
+### Other commands
+
+```bash
+bunx @reservine/dx update     # Pull latest skills from GitHub
+bunx @reservine/dx doctor     # Verify installation health
+bunx @reservine/dx uninstall  # Remove from Claude Code settings
+```
+
+### Manual installation
+
+If you prefer not to use the CLI, add to your `~/.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "reservine-dx": {
+      "source": {
+        "source": "git",
+        "url": "https://github.com/Reservine/Reservine-DX.git"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "reservine-dx@reservine-dx": true
+  }
+}
+```
+
+---
+
+## Developer Workflow
+
+The full feature lifecycle from idea to merged PR:
+
+```
+ ┌─────────────────────────────────────────────────────────────────┐
+ │  1. PLAN                                                       │
+ │  /reservine-dx:new-feature-planning full: voucher management   │
+ │                                                                │
+ │  → Creates GitHub issues in FE + BE repos                      │
+ │  → Links them via sub-issues (FE = parent)                     │
+ │  → Runs interactive questionnaire (scope: fe/be/full)          │
+ │  → Assigns milestone + priority labels                         │
+ └───────────────────────┬─────────────────────────────────────────┘
+                         │
+ ┌───────────────────────▼─────────────────────────────────────────┐
+ │  2. SETUP                                                      │
+ │                                                                │
+ │  BE: setup-worktree-be.sh --isolated                           │
+ │  → Creates worktree, copies vendor, starts isolated Docker     │
+ │  → Seeds DB from snapshot, runs migrations                     │
+ │  → Generates FE proxy.conf.json + config.local                 │
+ │                                                                │
+ │  FE: setup-worktree-fe.sh                                      │
+ │  → Symlinks node_modules, copies SSL certs                     │
+ │  → Detects BE isolated stack, sets proxy to correct port       │
+ │  → Writes MCP_WORKTREE_PORT to config.local                    │
+ │                                                                │
+ │  Result: FE worktree ←proxy→ BE isolated Docker                │
+ │          (completely isolated from main dev environment)        │
+ └───────────────────────┬─────────────────────────────────────────┘
+                         │
+ ┌───────────────────────▼─────────────────────────────────────────┐
+ │  3. IMPLEMENT                                                  │
+ │  /reservine-dx:implement-plan <issue-number>                   │
+ │                                                                │
+ │  Phase 1: Load issue context + dependency check                │
+ │  Phase 2: Questionnaire (delegated to local plugin.md)         │
+ │  Phase 3: Branch + worktree setup                              │
+ │  Phase 4: Implementation (delegated to local plugin.md)        │
+ │  Phase 5: Build verification (self-improvement loop, max 5)    │
+ │  Phase 6: E2E testing (auto-start server, Playwright, fix loop)│
+ │  Phase 7: Create PR                                            │
+ │  Phase 8-10: Code review, security audit, retro fixes          │
+ └───────────────────────┬─────────────────────────────────────────┘
+                         │
+ ┌───────────────────────▼─────────────────────────────────────────┐
+ │  4. CLEANUP                                                    │
+ │  /reservine-dx:cleanup                                         │
+ │                                                                │
+ │  → Discovers all artifacts (worktrees, Docker, branches)       │
+ │  → Verifies PRs are merged                                     │
+ │  → Kills processes, tears down Docker, removes worktrees       │
+ │  → Deletes local + remote branches                             │
+ │  → Cross-repo: finds and cleans sibling worktree automatically │
+ └─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## How Worktree Isolation Works
+
+Each feature gets its own isolated environment — separate from the main dev setup and from other features:
+
+```
+Main repos (always running on standard ports):
+  FE: localhost:1111 → BE: localhost:80 (shared Sail)
+
+Feature worktree (isolated):
+  FE: localhost:4202 → BE: localhost:8056 (own Docker stack)
+      ↑                     ↑
+      │ proxy.conf.json     │ docker-compose.isolated.yaml
+      │ auto-generated      │ deterministic ports from branch hash
+      │ by BE setup         │ own DB + Redis + Meilisearch
+      │                     │ seeded from snapshot
+      ↓                     ↓
+  .worktrees/feat/...    .worktrees/feat/...
+  (symlinked modules)    (copied vendor, isolated .env)
+```
+
+### Port Flow
+
+```
+setup-worktree-fe.sh
+  │ scans ports 4200-4205
+  │ finds first free port (e.g., 4202)
+  │ writes MCP_WORKTREE_PORT=4202 → .claude/config.local
+  ▼
+implement-plan (Phase 6)
+  │ reads MCP_WORKTREE_PORT from config.local
+  │ auto-starts: nx serve reservine --port 4202
+  ▼
+Playwright MCP (init-page.ts)
+  │ reads MCP_WORKTREE_PORT from config.local
+  │ overrides baseUrl → http://localhost:4202
+  │ authenticates, runs E2E tests
+  ▼
+cleanup
+  │ scans ports, kills nx serve on 4202
+  │ tears down Docker on 8056
+```
+
+### BE Isolated Docker Stack
+
+Each BE worktree gets deterministic ports based on branch name hash:
+
+```
+Branch: feat/voucher-management-114
+Slug:   feat-voucher-management-114
+Hash:   offset 42
+
+Ports:
+  App:      8042  (8000 + 42)
+  DB:       4342  (4300 + 42)
+  Redis:    7342  (7300 + 42)
+  Adminer:  9042  (9000 + 42)
+  Meili:    8742  (8700 + 42)
+
+Containers: wt-feat-voucher-management-114-{app,db,redis,adminer,meili,soketi}
+```
+
+Collision detection: if a port is already in use by another stack, the offset increments until a free range is found.
+
+---
+
+## Self-Improvement Loops
+
+The implement-plan skill uses structured fix loops at two levels:
+
+### Build Loop (Phase 5)
+
+```
+Run: bun run build:reservine:prod && nx lint reservine
+  ├─ PASS → proceed to Phase 6
+  └─ FAIL → read error → fix code → commit → re-run (max 5x)
+```
+
+### E2E Test Loop (Phase 6)
+
+```
+Run all E2E tests
+  ├─ ALL PASS → proceed to Phase 7
+  └─ FAILURES → classify each:
+       ├─ Implementation bug → fix source code
+       ├─ Test bug → fix selector/assertion
+       └─ Timing issue → add waitForSelector
+     → re-run ONLY failing tests (max 5x total)
+```
+
+Classification heuristics:
+| Error pattern | Classification |
+|---------------|---------------|
+| `TimeoutError: locator` | Timing issue |
+| `expect(received).toBe(expected)` wrong value | Implementation bug |
+| `locator resolved to 0 elements` | Test bug or impl bug |
+| `net::ERR_CONNECTION_REFUSED` | Server not running |
+
+---
+
+## Skills & Commands Reference
+
+### Skills
+
+| Skill | Scope prefix | Description |
+|-------|-------------|-------------|
+| `new-feature-planning` | `fe:` / `be:` / `full:` | Create GitHub issues with questionnaire, milestone, sub-issue linking |
+| `implement-plan` | — | Universal feature orchestrator with 10 phases |
+| `cross-plan` | — | Create intent files + linked issues in sibling repo |
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `cherry-pick-pr` | Extract commits into a clean PR via worktree |
+| `commit` | Smart commits with stack-aware pre-checks and task ID detection |
+| `cleanup` | Post-merge cleanup of all artifacts across both repos |
+
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `setup-worktree.sh` | Entry point — auto-detects Angular/Laravel |
+| `setup-worktree-fe.sh` | Angular: node_modules, SSL, proxy, port detection |
+| `setup-worktree-be.sh` | Laravel: vendor, Sail, isolated Docker, snapshot seeding |
+| `_core.sh` | Shared: colors, logging, env detection, branch setup, sibling lookup |
+
+Use `--log` on any setup script to write a timestamped log file.
+
+---
+
+## Architecture
+
+```
+Reservine-DX/                    # This marketplace (shared, cross-repo)
+├── bin/
+│   └── cli.ts                   # bunx @reservine/dx CLI (install/update/doctor)
+├── plugins/reservine-dx/
+│   ├── skills/
+│   │   ├── new-feature-planning # Issue creation + questionnaire
+│   │   ├── cross-plan           # Bidirectional intent files
+│   │   └── implement-plan       # Shared orchestrator
+│   │       └── references/
+│   │           └── plugin-contract
+│   ├── commands/
+│   │   ├── cherry-pick-pr       # Worktree-based cherry-pick
+│   │   ├── commit               # Smart commits
+│   │   └── cleanup              # Post-merge cleanup
+│   ├── scripts/
+│   │   ├── _core.sh             # Shared utilities
+│   │   ├── setup-worktree.sh    # Auto-detect entry point
+│   │   ├── setup-worktree-fe.sh # Angular worktree setup
+│   │   └── setup-worktree-be.sh # Laravel worktree setup
+│   └── docker/worktree/
+│       ├── docker-compose.isolated.template.yaml
+│       └── seed-snapshot.sh
+
+reservine/.claude/skills/        # FE-specific (stays local)
+├── implement-plan/plugin.md     # Angular: design critique, E2E, Nielsen audit
+├── design/                      # UI Composition Bible (83+ components)
+├── angular/                     # Signal patterns, TanStack Query
+├── i18n/                        # ICU MessageFormat translations
+├── layers/                      # Modal/drawer system
+├── grid-engine/                 # Calendar + timeslot picker
+└── play/                        # Playwright MCP routing
+
+ReservineBack/.claude/skills/    # BE-specific (stays local)
+├── implement-plan/plugin.md     # Laravel: API slice, PHPUnit, PHPStan
+├── api/                         # Full vertical slice builder
+├── laravel/                     # Best practices + patterns
+├── tdd/                         # Test-driven development
+└── dev-tools/                   # Debugging tools (Horizon, Telescope)
+```
+
+## Plugin Contract
+
+Each repo keeps `.claude/skills/implement-plan/plugin.md` following the contract in `references/plugin-contract.md`. Required sections:
+
+| Section | Purpose |
+|---------|---------|
+| `## Stack` | `angular` or `laravel` |
+| `## Specification Phase` | Questionnaire or design critique to run |
+| `## Implementation Phase` | Which skills to invoke, how to implement |
+| `## Build Commands` | `build`, `lint`, `typecheck`, `test` commands |
+| `## Verification Phase` | E2E tests, visual checks, type verification |
+| `## PR Template Extras` | Additional PR body sections |
+| `## Review Extras` | Stack-specific reviewer checklist |
+
+## Config System
+
+Both repos use `.claude/config` (committed) + `.claude/config.local` (gitignored):
+
+| Variable | Source | Used by |
+|----------|--------|---------|
+| `GITHUB_REPO` | `.claude/config` | PRs, `gh` commands |
+| `DEVELOPMENT_BRANCH` | `.claude/config` | Worktree base, PR target |
+| `BACKEND_DIR` / `FRONTEND_DIR` | `.claude/config` | Sibling repo path |
+| `MCP_WORKTREE_PORT` | `.claude/config.local` | Playwright MCP, dev server port |
+| `MCP_LOCALBE_API_URL` | `.claude/config.local` | Proxy target for isolated BE |
+| `MCP_DEV_EMAIL` / `PASSWORD` | `.claude/config.local` | Playwright auth credentials |