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

bunx @reservine/dx install

That's it. Restart Claude Code and the skills are available in any Reservine repo.

Other commands

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:

{
  "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 |