@reservine/dx 1.0.0

package/plugins/reservine-dx/skills/implement-plan/SKILL.md

@@ -0,0 +1,512 @@
+---
+name: reservine-dx:implement-plan
+description: >
+  Universal feature implementation orchestrator for the Reservine ecosystem. Works in both
+  FE (Angular) and BE (Laravel) repos by auto-detecting the stack and loading a local
+  plugin.md for stack-specific phases. Handles GitHub issue tracking, checkpoint resume,
+  label management, worktree setup, PR creation, code review, and security audit.
+  Triggers: "implement issue", "build feature #N", "implement plan", issue number or
+  intent file path argument.
+argument-hint: <issue-number-or-intent-file>
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Skill
+  - AskUserQuestion
+  - Agent
+  - ToolSearch
+---
+
+# Reservine — Implement Plan (Shared Orchestrator)
+
+End-to-end feature orchestrator that works in both the Angular frontend and Laravel backend
+repos. Auto-detects the current stack, loads the local `plugin.md` for stack-specific phases,
+and orchestrates the full feature lifecycle from issue to PR.
+
+`ToolSearch` is required because Playwright MCP tools (used in FE plugin) are deferred.
+
+## Stack Detection
+
+At startup, detect the current stack:
+
+```bash
+if [[ -f "angular.json" ]] || [[ -f "nx.json" ]]; then
+  STACK="angular"
+elif [[ -f "artisan" ]] || [[ -f "composer.json" ]]; then
+  STACK="laravel"
+else
+  # AskUserQuestion: "Which stack is this repo? (angular / laravel)"
+fi
+```
+
+Then load the local plugin:
+```bash
+cat .claude/skills/implement-plan/plugin.md
+```
+
+The plugin provides stack-specific configuration for phases delegated below.
+
+## GitHub Issue Tracking
+
+The GitHub issue is the **single source of truth** for plan progress. Throughout execution,
+post structured comments to the issue so progress is visible to anyone watching.
+
+**All commits** in the worktree MUST be prefixed with `[#<issue>]`:
+```
+[#<issue>] feat(<scope>): <description>
+```
+
+**Progress comments** are posted at these checkpoints:
+
+| Checkpoint | Comment Contains | Label Applied |
+|------------|-----------------|---------------|
+| After Phase 1 | Dependencies checked, codebase scan results | `status:in-progress` |
+| After Phase 2 | Specification (questionnaire/critique results) | `status:design-decided` (FE) / `status:architecture-decided` (BE) |
+| After Phase 3 | Branch name + worktree created | — |
+| After Phase 5 | Build/test verification results | `status:build-passing` (FE) / `status:tests-passing` (BE) |
+| After Phase 6 | Stack-specific verification results | `status:tests-passing` |
+| After Phase 7 | PR link | `status:pr-ready` |
+| After Phase 8 | Code review verdict + findings | — |
+| After Phase 9 | Security audit findings | — |
+| After Phase 10 | Fix list + deferred items | `status:review-passed` |
+
+Comment format:
+```bash
+gh issue comment <issue> --repo <GITHUB_REPO> --body "..."
+```
+
+Use collapsible `<details>` blocks for long content.
+
+**Note:** When input is an `.intent.md` file instead of an issue number, skip issue tracking
+(no issue to comment on). The PR will still reference the intent file.
+
+### Progress Labels
+
+Apply labels to the issue as phases complete:
+
+```bash
+gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:in-progress"
+gh issue edit <issue> --repo <GITHUB_REPO> --remove-label "status:in-progress" --add-label "status:design-decided"
+```
+
+Labels are cumulative except `status:*` which replaces the previous status.
+
+**IMPORTANT**: `gh issue edit --add-label` does NOT auto-create labels. Create them first:
+```bash
+gh label create "status:in-progress" --repo <GITHUB_REPO> --color "0E8A16" --description "Implementation in progress" 2>/dev/null || true
+gh label create "status:design-decided" --repo <GITHUB_REPO> --color "0E8A16" --description "Design/architecture decisions finalized" 2>/dev/null || true
+gh label create "status:architecture-decided" --repo <GITHUB_REPO> --color "1D76DB" --description "Architecture decisions finalized" 2>/dev/null || true
+gh label create "status:build-passing" --repo <GITHUB_REPO> --color "0E8A16" --description "Build passes" 2>/dev/null || true
+gh label create "status:tests-passing" --repo <GITHUB_REPO> --color "0E8A16" --description "All tests passing" 2>/dev/null || true
+gh label create "status:pr-ready" --repo <GITHUB_REPO> --color "FBCA04" --description "PR created and ready for review" 2>/dev/null || true
+gh label create "status:review-passed" --repo <GITHUB_REPO> --color "0E8A16" --description "Code review and security audit passed" 2>/dev/null || true
+gh label create "status:blocked" --repo <GITHUB_REPO> --color "B60205" --description "Blocked by dependency" 2>/dev/null || true
+```
+Run this label bootstrap in **Phase 1** (once per repo — labels persist).
+
+### Blocked Status
+
+If the skill encounters a blocker at any phase:
+
+1. Apply label:
+   ```bash
+   gh issue edit <issue> --repo <GITHUB_REPO> --remove-label "status:in-progress" --add-label "status:blocked"
+   ```
+
+2. Post blocking comment:
+   ```bash
+   gh issue comment <issue> --repo <GITHUB_REPO> --body "## Blocked
+
+   **Reason:** <description>
+   **Blocked by:** <linked issue(s) or external dependency>
+   **Technical details:** <what needs to happen before unblocking>
+   **Impact:** <what phases can't proceed>
+
+   **To unblock:** Resolve the above, then re-run \`/reservine-dx:implement-plan <issue>\` to resume from checkpoint."
+   ```
+
+3. Save checkpoint and exit gracefully.
+
+When resuming after unblock:
+```bash
+gh issue edit <issue> --repo <GITHUB_REPO> --remove-label "status:blocked" --add-label "status:in-progress"
+gh issue comment <issue> --repo <GITHUB_REPO> --body "Unblocked — resuming implementation from Phase <N>."
+```
+
+### Phase Timing
+
+Record wall-clock time for each phase. At the start of the skill, capture `START_TIME=$(date +%s)`.
+Before each phase, capture phase start time. After each phase, compute duration.
+
+Post cumulative timing to the issue in the final PR comment.
+
+### Checkpoint Resume
+
+Save execution state after each phase to `.worktrees/<branch>/.checkpoint.json`:
+
+```json
+{
+  "issue": 114,
+  "stack": "angular",
+  "milestone": "v2.5",
+  "branch": "feat/voucher-management-114",
+  "currentPhase": 5,
+  "completedPhases": [1, 2, 3, 4],
+  "specification": { ... },
+  "timing": { "phase1": 15, "phase2": 130, ... },
+  "featureScope": "voucher-management",
+  "codeReview": { "critical": [], "important": [], "minor": [], "verdict": "Ready" },
+  "securityAudit": { "critical": [], "important": [], "advisory": [] }
+}
+```
+
+**On startup (Phase 1)**, before loading the issue, check for an existing checkpoint:
+```bash
+ls .worktrees/*/.checkpoint.json 2>/dev/null
+```
+
+If found, present to user via `AskUserQuestion`:
+- **Resume from Phase N** — continue where we left off
+- **Start fresh** — ignore checkpoint, begin from Phase 1
+- **View checkpoint** — show saved state before deciding
+
+---
+
+## Phase 1: Load Feature Context
+
+1. Read `.claude/config` + `.claude/config.local` for project variables:
+   - `DEVELOPMENT_BRANCH` — base branch for worktree + PR target
+   - `GITHUB_REPO` — org/repo for `gh` commands
+   - `BACKEND_DIR` / `FRONTEND_DIR` — sibling repo paths
+
+2. Determine input type from `$ARGUMENTS`:
+   - **If a number**: Load GitHub issue:
+     ```bash
+     gh issue view $ARGUMENTS --repo <GITHUB_REPO> --json title,body,labels,number,milestone
+     ```
+   - **If a file path**: Read the `.intent.md` file from `.claude/plans/future/`
+
+3. Check for companion files in the sibling repo:
+   - Intent files in `<SIBLING_DIR>/.claude/plans/future/`
+   - Existing plans in `.claude/plans/active/`
+
+4. Extract: feature description, data shapes, endpoint paths, requirements
+
+### Implementation Checklist Detection
+
+Check if the issue body contains an "Implementation Checklist" section:
+```bash
+BODY=$(gh issue view <issue> --repo <GITHUB_REPO> --json body --jq '.body')
+if echo "$BODY" | grep -q "## Implementation Checklist"; then
+  echo "Implementation Checklist found — will check off items as phases complete"
+fi
+```
+
+5. **Dependency check** — scan issue body and linked issues for blockers:
+   ```bash
+   gh api repos/<GITHUB_REPO>/issues/<issue>/timeline --jq '.[] | select(.event=="cross-referenced")'
+   ```
+   If dependencies found (open blocking issues), warn user via `AskUserQuestion`:
+   - **Proceed anyway** — dependency may not be strictly required
+   - **Abort** — wait for dependencies to be resolved
+
+6. **Pre-flight codebase scan** — auto-detect existing related code:
+   - Use patterns from the loaded plugin (FE searches `apps/`, BE searches `app/`)
+   - Present scan results: "Found N related files. Pre-filling questionnaire answers."
+
+7. **Auto-link sibling issue/PR** — find the corresponding issue in the sibling repo:
+   ```bash
+   gh search issues "<feature-keyword>" --repo <SIBLING_GITHUB_REPO> --json number,title,state --limit 5
+   ```
+
+8. **Bootstrap labels** (idempotent) and **post to issue**:
+   ```bash
+   gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:in-progress"
+   gh issue comment <issue> --repo <GITHUB_REPO> --body "## Implementation Plan Started
+
+   **Dependencies:** <none / list with status>
+   **Related code found:** <N files>
+   **Sibling reference:** <link or 'none found'>
+   **Mode:** <New / Extension>"
+   ```
+
+## Phase 2: Specification (DELEGATED TO PLUGIN)
+
+**Read the plugin's `## Specification Phase` section** and execute it.
+
+The plugin defines what questionnaire or critique to run:
+- **Angular plugin**: Apple Design Director critique via Playwright MCP + UI/UX questionnaire (14 questions)
+- **Laravel plugin**: Architecture questionnaire (14 questions about data model, API scope, permissions, etc.)
+
+After the plugin's specification phase completes:
+1. Compile answers into a specification document
+2. Present to user for confirmation via `AskUserQuestion`
+3. Post specification to issue as a collapsible `<details>` comment
+4. Apply the appropriate status label (`status:design-decided` or `status:architecture-decided`)
+
+## Phase 3: Branch & Worktree Setup
+
+1. Derive branch name: `feat/<kebab-slug>-<issue>` (max 50 char slug)
+   - Confirm with user via `AskUserQuestion`
+2. Pre-flight:
+   ```bash
+   git fetch origin <DEVELOPMENT_BRANCH>
+   git rev-parse --verify --quiet <branch>
+   git ls-remote --exit-code --heads origin <branch>
+   ```
+3. Create worktree:
+   ```bash
+   git worktree add .worktrees/<branch> origin/<DEVELOPMENT_BRANCH> -b <branch>
+   ```
+4. **Run stack-specific worktree setup** from the plugin:
+   - Angular: Copy SSL certs, symlink node_modules, copy proxy config
+   - Laravel: Copy .env, setup vendor (symlink or install), run migrations
+
+5. Verify worktree initialization (Critical Operation):
+   ```bash
+   [[ -d .worktrees/<branch> ]] && echo "OK: worktree" || echo "FAIL: worktree missing"
+   ```
+
+6. **Post to issue**:
+   ```bash
+   gh issue comment <issue> --repo <GITHUB_REPO> --body "## Branch Created
+
+   **Branch:** \`<branch>\`
+   **Worktree:** \`.worktrees/<branch>\`"
+   ```
+
+## Phase 4: Implementation (DELEGATED TO PLUGIN)
+
+**Read the plugin's `## Implementation Phase` section** and execute it.
+
+The plugin defines which skills to invoke and how to implement:
+- **Angular plugin**: Invokes `reservine:design`, `reservine:angular`, `reservine:i18n`, implements
+  components/services/routes, runs build verification loops
+- **Laravel plugin**: Invokes `reservine:api` for full vertical slice (migration, model, service,
+  DTOs, controller, routes), creates FE cross-plan intent file
+
+All implementation work happens inside the worktree directory.
+
+## Phase 5: Build Verification
+
+**Read the plugin's `## Build Commands` section** for the correct commands.
+
+Run the build verification commands from the plugin:
+
+```
+Angular:  bun run build:reservine:prod && nx lint reservine
+Laravel:  vendor/bin/phpstan analyze <changed-files> && vendor/bin/sail test
+```
+
+### Self-Improvement Loop
+
+If build fails:
+1. Read the error output
+2. Fix the issues in the worktree
+3. Re-run the build commands
+4. Repeat until ALL pass (max 5 iterations)
+5. If still failing after 5 iterations, `AskUserQuestion` for guidance
+
+Post build results to issue:
+```bash
+gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:build-passing"
+```
+
+## Phase 6: Verification (DELEGATED TO PLUGIN)
+
+**Read the plugin's `## Verification Phase` section** and execute it.
+
+### Worktree Port Resolution
+
+Before running any verification, resolve the worktree dev server port:
+
+```bash
+# Read from worktree config (set by setup-worktree-fe.sh)
+WORKTREE_PORT=$(grep '^MCP_WORKTREE_PORT=' .claude/config.local 2>/dev/null | cut -d= -f2)
+WORKTREE_PORT=${WORKTREE_PORT:-4200}
+```
+
+Save `WORKTREE_PORT` in `.checkpoint.json` for resume.
+
+The plugin defines stack-specific verification:
+- **Angular plugin**: Auto-starts dev server on `$WORKTREE_PORT`, runs Playwright MCP
+  (which reads `MCP_WORKTREE_PORT` from config.local via init-page.ts), generates E2E tests
+  from issue body + git diff, runs Classify → Fix → Retest loop (max 5), design heuristic audit
+- **Laravel plugin**: PHPUnit test suite (happy + edge + error + obscure paths), API response
+  type verification, E2E integration checks
+
+### Self-Improvement Loop (Classify → Fix → Retest)
+
+When verification fails, use the structured fix loop:
+
+1. **Classify** each failure:
+   - **Implementation bug** — source code is wrong → fix component/service/template
+   - **Test bug** — selector or assertion is wrong → fix the test
+   - **Timing issue** — element not ready → add wait/retry
+2. **Fix** only the classified category, commit with appropriate prefix
+3. **Retest** only the previously-failing tests (not the full suite)
+4. **Repeat** until all pass (max 5 iterations)
+5. If still failing → `AskUserQuestion` for guidance
+
+Post verification results to issue:
+```bash
+gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:tests-passing"
+```
+
+## Phase 7: Create PR
+
+1. Stage and commit any remaining changes
+2. Push the branch:
+   ```bash
+   cd .worktrees/<branch>
+   git push -u origin <branch>
+   ```
+
+3. **Read the plugin's `## PR Template Extras` section** for additional PR body content.
+
+4. Create the PR:
+   ```bash
+   cd .worktrees/<branch>
+   gh pr create --base <DEVELOPMENT_BRANCH> --title "<PR title>" --body "$(cat <<'EOF'
+   ## Summary
+   <1-3 sentences describing the feature>
+
+   ## Changes
+   <bullet list of what changed>
+
+   ## Related
+   - Issue: #<issue>
+   - <sibling repo references>
+
+   <PLUGIN PR EXTRAS>
+
+   ## Implementation Timing
+   <phase timing table>
+
+   ## Test Plan
+   - [ ] <test items from plugin>
+   EOF
+   )"
+   ```
+
+5. Post to issue:
+   ```bash
+   gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:pr-ready"
+   gh issue comment <issue> --repo <GITHUB_REPO> --body "## PR Created
+
+   <PR-URL>"
+   ```
+
+## Phase 8: Code Review
+
+Self-review the changes against these categories:
+
+### Review Checklist
+
+| Category | Check |
+|----------|-------|
+| **Architecture** | Single responsibility, proper layering, no circular deps |
+| **Security** | Input validation, auth checks, no secrets in code |
+| **Performance** | No N+1 queries, proper indexing, lazy loading |
+| **Error Handling** | Graceful failures, user-facing messages, logging |
+| **Testing** | Coverage of happy + edge + error paths |
+| **Code Quality** | Naming, DRY, no dead code, consistent patterns |
+
+Also check plugin-specific items from `## Review Extras` (if defined).
+
+### Findings Classification
+
+| Severity | Action |
+|----------|--------|
+| **Critical** | Must fix before merge — security, data loss, crashes |
+| **Important** | Should fix — logic errors, missing validation, bad UX |
+| **Minor** | Nice to have — naming, formatting, minor refactors |
+| **Positive** | Call out well-done patterns |
+
+Post findings to issue comment.
+
+## Phase 9: Security Audit
+
+Spawn a security-auditor agent to review the changes:
+
+### OWASP Top 10 Check
+- Injection (SQL, XSS, command)
+- Broken authentication
+- Sensitive data exposure
+- Security misconfiguration
+- Known vulnerabilities in deps
+
+### Multi-tenant / GDPR Check (Reservine-specific)
+- Tenant isolation — no cross-tenant data leaks
+- Personal data handling — consent, deletion, export
+- Session management — proper token handling
+- Permission enforcement — RBAC consistency
+
+Post findings to issue comment.
+
+## Phase 10: Retro Fixes
+
+Fix all **Critical** and **Important** findings from Phases 8-9.
+
+1. For each finding:
+   - Fix the code in the worktree
+   - Commit with message: `[#<issue>] fix(<scope>): <finding description>`
+2. Re-run build verification (Phase 5 commands)
+3. Re-run relevant verification (Phase 6 — only affected tests)
+4. Push fixes
+5. Update PR description with fix summary
+
+### Deferred Items
+
+For **Minor** findings that aren't worth fixing now:
+1. List them in the PR description under "## Deferred"
+2. Optionally create follow-up issues
+
+Post final status to issue:
+```bash
+gh issue edit <issue> --repo <GITHUB_REPO> --add-label "status:review-passed"
+gh issue comment <issue> --repo <GITHUB_REPO> --body "## Implementation Complete
+
+**Fixes applied:** <count>
+**Deferred:** <count>
+**PR:** <url>
+
+**Timing:**
+<phase timing table>"
+```
+
+---
+
+## Plugin Contract
+
+The local `plugin.md` file (at `.claude/skills/implement-plan/plugin.md`) MUST follow the
+contract defined in `references/plugin-contract.md`. See that file for the required sections
+and format.
+
+## Config Variables
+
+| Variable | Source | Purpose |
+|----------|--------|---------|
+| `GITHUB_REPO` | `.claude/config` | Current repo for `gh` commands |
+| `DEVELOPMENT_BRANCH` | `.claude/config` | Base branch for PR |
+| `FRONTEND_DIR` / `BACKEND_DIR` | `.claude/config` | Sibling repo path |
+| `*_ABSOLUTE` variants | `.claude/config.local` | Worktree-safe absolute paths |
+| `MCP_*` variables | `.claude/config` + `.claude/config.local` | Dev/E2E server access |
+
+## Error Recovery
+
+| Phase | Failure | Recovery |
+|-------|---------|----------|
+| 1 | Issue not found | Check number, verify repo access |
+| 1 | Sibling config not found | Use defaults |
+| 2 | User cancels questionnaire | Save partial checkpoint, exit |
+| 3 | Worktree creation fails | Delete existing branch, retry |
+| 4 | Implementation error | Fix, commit, continue |
+| 5 | Build fails after 5 retries | AskUserQuestion for guidance |
+| 6 | Tests fail after 5 retries | AskUserQuestion for guidance |
+| 7 | PR creation fails | Check auth, verify branch pushed |
+| Any | Unexpected blocker | Apply blocked label, save checkpoint |

package/plugins/reservine-dx/skills/implement-plan/references/plugin-contract.md

@@ -0,0 +1,82 @@
+# Implement-Plan Plugin Contract
+
+Version: 1
+
+The shared `reservine-dx:implement-plan` orchestrator delegates stack-specific phases to a
+local `plugin.md` file at `.claude/skills/implement-plan/plugin.md` in each repo.
+
+## Required Sections
+
+Your `plugin.md` MUST contain these sections with the exact heading names:
+
+### `## Stack`
+
+Single line: `angular` or `laravel`
+
+### `## Specification Phase`
+
+Define the questionnaire or critique to run during Phase 2:
+- What questions to ask (table format)
+- Any pre-specification steps (e.g., Playwright screenshots for design critique)
+- How to compile results into a specification document
+
+### `## Implementation Phase`
+
+Define how to implement the feature during Phase 4:
+- Which skills to invoke (e.g., `reservine:api`, `reservine:design`)
+- Implementation patterns and conventions
+- File creation/modification guidelines
+
+### `## Build Commands`
+
+Key-value pairs for build verification (Phase 5):
+
+```
+build: <command>
+lint: <command>
+typecheck: <command>
+test: <command>
+```
+
+### `## Verification Phase`
+
+Define stack-specific verification during Phase 6:
+- Visual checks (screenshots, design audit)
+- E2E tests (Playwright for FE, PHPUnit for BE)
+- Type verification, API response checks
+
+### `## PR Template Extras`
+
+Additional sections to include in the PR body (Phase 7):
+- Stack-specific test results
+- Design screenshots
+- Type generation status
+
+### `## Review Extras` (optional)
+
+Additional code review checklist items specific to the stack.
+
+## Example Plugin Structure
+
+```markdown
+## Stack
+angular
+
+## Specification Phase
+<instructions>
+
+## Implementation Phase
+<instructions>
+
+## Build Commands
+build: bun run build:reservine:prod
+lint: nx lint reservine
+typecheck: nx run reservine:typecheck
+test: pnpm test
+
+## Verification Phase
+<instructions>
+
+## PR Template Extras
+<content>
+```