npm package: @reservine/dx
Description: Shared developer experience skills for the Reservine ecosystem
Author: Reservine
Latest version: 3.6.0

# 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:worktree: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 |

---

## Commands Reference

| Command | Description |
|---------|-------------|
| `new-feature-planning` | Create GitHub issues with questionnaire, milestone, sub-issue linking (`fe:` / `be:` / `full:` scope) |
| `implement-plan` | Universal feature orchestrator with 11 phases (worktree, spec, build, E2E, PR, review) |
| `cross-plan` | Create intent files + linked issues in sibling repo (bidirectional FE↔BE) |
| `check-pr` | Address PR review comments — validates, fixes, explains, pushes, replies to each thread |
| `cherry-pick-into-pr` | Extract commits into a clean PR via worktree |
| `commit` | Smart commits with stack-aware pre-checks and task ID detection |
| `report-bug` | Report a bug with auto-investigation, root cause analysis, and fix offer |
| `remember` | Remember what you were working on — context, worktrees, Docker, next action |
| `worktree: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/
│   ├── commands/
│   │   ├── new-feature-planning # Issue creation + questionnaire
│   │   ├── implement-plan       # 11-phase feature orchestrator
│   │   ├── cross-plan           # Bidirectional intent files
│   │   ├── check-pr              # Address PR review feedback
│   │   ├── cherry-pick-into-pr  # Worktree-based cherry-pick
│   │   ├── commit               # Smart commits
│   │   ├── remember        # Resume work on existing feature
│   │   └── worktree:cleanup       # Post-merge cleanup
│   ├── references/
│   │   └── plugin-contract      # Contract for local plugin.md
│   ├── 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 |