@hopla/claude-setup 1.4.5 → 1.6.0

package/README.md

@@ -163,20 +163,20 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 
 ### Feature development (PIV loop)
 ```
-/hopla-prime          → load context at session start
-/hopla-plan-feature   → research codebase and create plan
-/hopla-review-plan    → review plan summary and approve
-/hopla-execute        → implement the plan with validation
-/hopla-code-review    → technical review of changes
-/hopla-code-review-fix → fix issues found
-/hopla-git-commit     → save to git
-/hopla-git-pr         → open pull request on GitHub
+/hopla-prime            → load context at session start
+/hopla-plan-feature     → research codebase and create plan
+/hopla-review-plan      → review plan summary and approve
+/hopla-execute          → implement the plan with validation
+/hopla-code-review      → standalone review of changes
+/hopla-code-review-fix  → fix issues found
+/hopla-execution-report → document what was built
+/hopla-git-commit       → save to git
+/hopla-git-pr           → open pull request on GitHub
 ```
 
 ### After implementation
 ```
-/hopla-execution-report  → document what was built
-/hopla-system-review     → analyze plan vs. actual for process improvements
+/hopla-system-review    → analyze plan vs. actual for process improvements
 ```
 
 > **Tip:** `hopla-prime`, `hopla-git-commit`, `hopla-git-pr`, `hopla-code-review`, and `hopla-execution-report` also exist as skills — they auto-activate when you describe what you want in natural language, without typing the slash command.
@@ -202,30 +202,46 @@ Commands are modular — the output of one becomes the input of the next. Some c
 /hopla-plan-feature add user authentication
 → saves: .agents/plans/add-user-authentication.md
 
-# 2. Execute
+# 2. Review plan
+/hopla-review-plan .agents/plans/add-user-authentication.md
+
+# 3. Execute
 /hopla-execute .agents/plans/add-user-authentication.md
 → implements the plan, runs validation
 
-# 3. Review
+# 4. Code review
 /hopla-code-review
 → saves: .agents/code-reviews/add-user-authentication.md
 
-# 4. Fix issues
+# 5. Fix issues
 /hopla-code-review-fix .agents/code-reviews/add-user-authentication.md
 
-# 5. Commit
-/hopla-git-commit
-
 # 6. Document
 /hopla-execution-report
 → saves: .agents/execution-reports/add-user-authentication.md
 
-# 7. Improve process
+# 7. Commit
+/hopla-git-commit
+
+# 8. Pull request
+/hopla-git-pr
+
+# 9. Process improvement (after PR merge)
 /hopla-system-review .agents/plans/add-user-authentication.md .agents/execution-reports/add-user-authentication.md
 ```
 
 ---
 
+## Roadmap
+
+Features under consideration for future versions:
+
+- **Custom subagents** (`.claude/agents/`) — Define specialized agents with their own instructions and skills for large projects with isolated domains (e.g. frontend agent, backend agent)
+- **Hook templates** — Installable hook patterns beyond tsc-check and env-protect (e.g. query deduplication, notification hooks)
+- **GitHub Actions integration** — Automated PR reviews and `@claude` mentions via GitHub App
+
+---
+
 ## Project Structure (after /hopla-init-project)
 
 ```

package/files/commands/hopla-code-review-fix.md

@@ -3,6 +3,8 @@ description: Fix issues found in a code review report
 argument-hint: "<review-file-or-description> [scope]"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Fix the issues identified in a code review.
 
 ## Inputs
@@ -44,3 +46,8 @@ Provide a summary of:
 - Issues skipped and why (if $2 scope was used)
 - Validation result ✅/❌
 - Any issues that could not be fixed automatically and require human review
+
+## Next Step
+
+After all fixes pass validation, suggest:
+> "All review issues fixed and validation passed. Run `/hopla-execution-report` to document the implementation, then `/hopla-git-commit` to commit."

package/files/commands/hopla-code-review.md

@@ -3,6 +3,8 @@ description: Technical code review on recently changed files
 argument-hint: "[optional: branch or commit range, defaults to HEAD]"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Perform a technical code review focused on finding real bugs and issues.
 
 ## Step 1: Load Context
@@ -77,3 +79,8 @@ If no issues found: "Code review passed. No technical issues detected."
 - Focus on real bugs, not style preferences (linting handles that)
 - Flag security issues as `critical`
 - Suggest fixes, don't just identify problems
+
+## Next Step
+
+After the review, suggest:
+> "Code review saved to `.agents/code-reviews/[name].md`. If issues were found, run `/hopla-code-review-fix .agents/code-reviews/[name].md` to fix them. If the review passed clean, proceed to `/hopla-execution-report`."

package/files/commands/hopla-create-prd.md

@@ -2,6 +2,8 @@
 description: Create or update the PRD for this project through guided questions
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Create or update a `PRD.md` for this project following the Layer 1 Planning approach: an exploratory conversation that defines scope, reduces assumptions, and generates both a `PRD.md` and supporting on-demand context documents.
 
 **If a `PRD.md` already exists**, this command will read it first and only ask about what's missing, outdated, or changing — it will not start from scratch.

package/files/commands/hopla-execute.md

@@ -3,6 +3,8 @@ description: Execute a structured plan from start to finish with validation
 argument-hint: "<plan-file-path>"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Execute the implementation plan provided. You are the executing agent — you have not seen the planning conversation. The plan is your only source of truth.
 
 ## Step 1: Load Context
@@ -40,17 +42,28 @@ Use when a plan assumption does not match reality:
 - **Recommendation:** [Replan X | Fix Y | Proceed with caution because Z]
 ```
 
-## Step 2: Verify Git Branch
+## Step 2: Verify Git State
 
 ```bash
 git branch --show-current
 git status
 ```
 
+### Clean working tree check
+
+If there are uncommitted changes, **stop and warn the user**:
+> "There are uncommitted changes in the working tree. These will be mixed into the implementation and make it harder to review and revert. Please commit or stash them before continuing."
+
+Do not proceed until the working tree is clean.
+
+### Branch check
+
 Check that the current branch follows Git Flow:
 - **Never execute on `main` or `master`** — stop and warn the user
 - **If on `develop`/`dev`** — ask: "You're on `develop`. Should I create a feature branch first? (recommended: `feature/[plan-name]`)"
 - **If on a `feature/`, `fix/`, or `hotfix/` branch** — proceed
+- **If the plan specifies a base branch** (in `## Git Strategy`) — verify the current branch was created from that base. If not, warn the user:
+  > "The plan specifies base branch `[X]` but the current branch was created from `[Y]`. This may cause the PR to target the wrong branch. Continue anyway?"
 
 If a new branch is needed, propose the name and wait for confirmation before creating it:
 ```bash
@@ -88,6 +101,19 @@ Work through each task in the plan sequentially. For each task:
 
 Do not improvise silently. When in doubt, stop and ask.
 
+### Scope Guard
+
+If the user requests changes that are NOT in the plan during execution:
+
+1. **Acknowledge** the request
+2. **Assess** whether it's a small adjustment (< 5 minutes, same files) or a new feature
+3. **If small adjustment:** implement it and flag it as a deviation in the completion report
+4. **If new feature or significant addition:**
+   - Suggest committing the current planned work first
+   - Then create a new branch or add it to the backlog
+   - Say: "This looks like a separate feature. I recommend we commit the current work first, then handle this in a new branch. Should I add it to `.agents/plans/backlog/` instead?"
+5. **Never** silently add significant unplanned work — scope creep caused the lowest alignment score (6/10) in past implementations
+
 ## Step 5: Run Full Validation Pyramid
 
 After all tasks are complete, run the full validation sequence in order.
@@ -114,7 +140,22 @@ If tests fail:
 Run integration tests or manual verification as specified in the plan (e.g. `npm run test:e2e`, manual curl).
 Verify the feature works end-to-end.
 
-### Level 5 — Human Review (flag for user)
+### Level 5 — Code Review
+Run a code review on all changed files following the `/hopla-code-review` process. This catches bugs that linting, types, and tests miss (security issues, logic errors, pattern violations).
+
+If the review finds critical or high severity issues, **fix them before proceeding**.
+
+### Level 6 — File Drift Check
+Compare the files actually changed against the plan's task list:
+
+```bash
+git diff --name-only
+git ls-files --others --exclude-standard
+```
+
+Flag any files that were changed but are **not listed in any task**. These are potential scope leaks — unplanned additions that didn't get the same scrutiny as planned tasks. Report them in the completion summary so the user can review.
+
+### Level 7 — Human Review (flag for user)
 List what the user should manually verify:
 - Specific behaviors to test in the browser or CLI
 - Edge cases to check
@@ -136,11 +177,13 @@ Provide a summary of what was done:
 - [ ] Task 3: [description — if skipped, explain why]
 
 ### Validation Results
-- Level 1 Lint:       ✅ / ❌
-- Level 2 Type Check: ✅ / ❌
-- Level 3 Unit Tests: ✅ [X passed] / ❌ [X failed]
-- Level 4 Integration:✅ / ❌
-- Level 5 Human:      🔍 See items below
+- Level 1 Lint:        ✅ / ❌
+- Level 2 Type Check:  ✅ / ❌
+- Level 3 Unit Tests:  ✅ [X passed] / ❌ [X failed]
+- Level 4 Integration: ✅ / ❌
+- Level 5 Code Review: ✅ [X issues found, all fixed] / ❌
+- Level 6 File Drift:  ✅ [all files in plan] / ⚠️ [X unplanned files]
+- Level 7 Human:       🔍 See items below
 
 ### For Human Review
 - [specific thing to verify manually]
@@ -152,6 +195,7 @@ Provide a summary of what was done:
 ## Step 7: Suggest Next Steps
 
 After the summary, suggest:
-1. Run `/hopla-execution-report` to document this implementation for system review
-2. Run `/hopla-code-review` for a technical quality check
-3. Run `/hopla-git-commit` once everything is approved
+1. Run `/hopla-code-review` for a standalone review of the changes (recommended — a fresh review catches issues the executing agent may have missed)
+2. If issues are found, run `/hopla-code-review-fix` to fix them
+3. Run `/hopla-execution-report` to document the implementation
+4. Run `/hopla-git-commit` to commit the changes

package/files/commands/hopla-execution-report.md

@@ -2,6 +2,8 @@
 description: Generate an implementation report for system review
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Review and document the implementation you just completed. Run this immediately after finishing a feature — before committing or starting the next task.
 
 ## Step 1: Gather Implementation Data
@@ -65,3 +67,8 @@ Based on this implementation, what should change for next time?
 - Plan command improvements: [suggestions]
 - Execute command improvements: [suggestions]
 - CLAUDE.md additions: [suggestions]
+
+## Next Step
+
+After the report is saved, suggest:
+> "Execution report saved to `.agents/execution-reports/[name].md`. Run `/hopla-git-commit` to commit your changes."

package/files/commands/hopla-git-commit.md

@@ -3,6 +3,8 @@ description: Create a conventional commit with Git Flow awareness
 argument-hint: "[optional: commit message or scope]"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Review the current git state and create an appropriate commit.
 
 ## Step 1: Gather Context
@@ -58,3 +60,6 @@ After committing, remind the user:
 > "Commit created locally. Do you want to push to `origin/<branch>`?"
 
 **Never push automatically** — wait for explicit confirmation.
+
+If the user confirms the push (or if the branch was already pushed), suggest:
+> "Ready to create a Pull Request? Run `/hopla-git-pr` to create one."

package/files/commands/hopla-git-pr.md

@@ -3,6 +3,8 @@ description: Create a GitHub Pull Request with a structured description
 argument-hint: "[optional: base branch, defaults to develop]"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Create a Pull Request on GitHub for the current branch.
 
 ## Step 1: Gather Context
@@ -20,9 +22,23 @@ Read the following if they exist:
 
 ## Step 2: Determine Base Branch
 
-- If `$1` is provided, use it as the base branch
-- Otherwise default to `develop` (or `dev` if that's what the project uses)
-- If on `main` or `develop` directly, warn the user: "You're on `[branch]` — PRs should come from feature branches."
+**If `$1` is provided**, use it as the base branch.
+
+**Otherwise, infer from Git Flow branch naming:**
+
+| Current branch prefix | Base branch |
+|---|---|
+| `feature/*` | `develop` or `dev` |
+| `fix/*` | `develop` or `dev` |
+| `hotfix/*` | `main` |
+| `release/*` | `main` |
+
+To resolve `develop` vs `dev`: run `git branch -r` and look for `origin/develop` or `origin/dev`. Use whichever exists.
+
+**Guard rails:**
+- If the current branch is `main`, `master`, `develop`, or `dev` → stop and warn: "You're on `[branch]` — PRs should come from feature branches."
+- If the branch name doesn't match any Git Flow prefix → ask the user: "I can't determine the base branch from `[branch]`. Should this PR target `develop` or `main`?"
+- **Always show the resolved base branch in Step 5** so the user can catch mistakes before the PR is created.
 
 ## Step 3: Check Push Status
 
@@ -80,3 +96,41 @@ gh pr create --title "[title]" --body "[body]" --base [base-branch]
 After creating, show the PR URL to the user.
 
 **Never merge automatically** — the PR is for human review.
+
+After showing the PR URL, suggest:
+> "PR created. To complete the cycle, run `/hopla-execution-report` (if not done yet) and `/hopla-system-review` after the PR is merged."
+
+## Step 7: Post-Merge Cleanup
+
+After the user confirms the PR was approved and merged on GitHub, run the cleanup workflow based on the branch type:
+
+### For all branch types:
+
+```bash
+git checkout [base-branch]
+git pull origin [base-branch]
+git branch -d [merged-branch]
+git push origin --delete [merged-branch] 2>/dev/null  # skip if GitHub already deleted it
+```
+
+### Additional steps for `hotfix/*` and `release/*`:
+
+These branches were merged to `main` but `develop` also needs the changes:
+
+```bash
+git checkout develop
+git pull origin develop
+git merge main
+git push origin develop
+```
+
+Then create a version tag:
+
+```bash
+git tag -a v[version] -m "Release [version]"
+git push origin v[version]
+```
+
+Ask the user for the version number before tagging.
+
+**Always confirm each destructive action** (branch deletion, tag creation) before executing.

package/files/commands/hopla-init-project.md

@@ -2,6 +2,8 @@
 description: Initialize a new project with a CLAUDE.md and .agents/ structure
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Set up the Layer 1 planning foundation for this project: a project-specific `CLAUDE.md` with rules and architecture decisions, plus the `.agents/` directory structure.
 
 > Layer 1 = Global Rules (~/.claude/CLAUDE.md) + Project Rules (CLAUDE.md) + PRD

package/files/commands/hopla-plan-feature.md

@@ -3,6 +3,8 @@ description: Research the codebase and create a structured implementation plan f
 argument-hint: "<feature-name-or-description>"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Transform the requirements discussed in this conversation into a structured plan that another agent can execute without access to this conversation.
 
 ## Phase 1: Understand the Requirements
@@ -23,6 +25,7 @@ Read the following to understand the project:
 2. `README.md` — project overview and setup
 3. `package.json` or `pyproject.toml` — stack, dependencies, scripts
 4. `.agents/guides/` — if this directory exists, read any guides relevant to the feature being planned (e.g. `@.agents/guides/api-guide.md` when planning an API endpoint)
+5. `MEMORY.md` (if it exists at project root or `~/.claude/`) — check for user preferences that affect this feature (UI patterns like modal vs inline, keyboard shortcuts, component conventions)
 
 Then run:
 
@@ -61,6 +64,9 @@ Based on research, define:
 - Any risks, edge cases, or gotchas to flag
 - What tests are needed
 - **Derived/computed values:** If any value is calculated from other fields, specify the exact formula including how stored values are interpreted (sign, units, semantics), AND how derived values propagate when inputs change (event system, reactivity, polling, etc.)
+- **Interaction states & edge cases:** For features involving interactive UI (forms, grids, keyboard navigation, wizards, CLI interactions), define a matrix of user interactions and their expected behavior. Cover: all keyboard shortcuts (both directions — e.g., Tab AND Shift+Tab), state transitions (empty → editing → saved → error), and boundary conditions (first item, last item, empty list, maximum items). This prevents iterative fix rounds that consumed up to 40% of session time in past implementations.
+- **API input validation:** For every API endpoint being created or modified, specify: required fields, field format constraints (e.g., "IMEI must be exactly 15 digits"), payload size limits, and what the user sees on validation failure. This was the #2 most common gap in past plans — validation was only added after code review in 4 of 7 implementations.
+- **User preferences check:** Before specifying UI architecture (modal vs. inline, page vs. panel, dialog vs. drawer), verify against MEMORY.md and conversation history for established preferences. In past implementations, plans that specified modals were rejected because the user preferred inline panels — this caused rework. When no preference exists, note it as a decision point for the user to confirm.
 
 ## Phase 5: Generate the Plan
 
@@ -82,6 +88,10 @@ Use this structure:
 ## Out of Scope
 - [Anything explicitly excluded]
 
+## Git Strategy
+- **Base branch:** `[develop | dev | main — specify which branch to create the feature branch from]`
+- **Feature branch:** `feature/[kebab-case-name]`
+
 ## Context References
 Key files the executing agent must read before starting:
 - `[path/to/file]` — [why it's relevant]
@@ -98,18 +108,41 @@ Key files the executing agent must read before starting:
 - **Details:** [Step-by-step description of what to implement]
 - **Gotcha:** [Known pitfall or constraint] — or `N/A`
 - **Validate:** [Exact command or check to confirm this task is done correctly]
+- **Time-box:** [Optional — for tasks with known technical risk, specify a maximum time and fallback. E.g., "30 min max. If auto-sizing doesn't work, fall back to fixed widths." Omit for straightforward tasks.]
+
+#### For tasks that create or modify API endpoints, also include:
+- **Validation:** [Required fields, input limits, format constraints (e.g. "IMEI must be exactly 15 digits")]
+- **Error UX:** [What the user sees when this operation fails (e.g. "toast.error with message", "inline error under field")]
 
 ### Task 2: [Action verb + what]
-[Same structure — all 6 fields required]
+[Same structure — all 6 required fields, plus optional Time-box]
 
 [Continue for all tasks...]
 
+## Interaction Matrix (if applicable)
+
+> Include this section when the feature involves interactive UI (grids, forms, keyboard navigation, drag-and-drop, wizards). Skip for pure backend/API features.
+
+| Action | Context | Expected Behavior |
+|--------|---------|-------------------|
+| [e.g., Tab] | [e.g., Last editable cell in row] | [e.g., Move to first cell of next row] |
+| [e.g., Escape] | [e.g., While editing a cell] | [e.g., Cancel edit, restore previous value] |
+
+Include: keyboard shortcuts (forward AND reverse), mouse interactions, state transitions, boundary conditions (first/last item, empty state, maximum items).
+
+## Test Tasks
+
+> Every plan must include at least one task that creates or updates tests. If the feature is purely UI with no testable logic, specify which interactions to verify manually and why automated tests are not applicable.
+
+> **Regression check:** If this feature modifies existing interactive functionality (editing flows, keyboard navigation, API endpoints with existing consumers), include a task to smoke-test the existing behavior AFTER implementation. In past implementations, changes to shared utilities broke existing interactions that weren't covered by the plan's task list.
+
 ## Validation Checklist
 
 Run in this order — do not proceed if a level fails:
 
 - [ ] **Level 1 — Lint & Format:** `[project lint command]`
 - [ ] **Level 2 — Type Check:** `[project type check command]`
+- [ ] **Level 2.5 — Code Review:** Run `/hopla-code-review` on changed files
 - [ ] **Level 3 — Unit Tests:** `[project unit test command]`
 - [ ] **Level 4 — Integration Tests:** `[project integration test or manual curl/check]`
 - [ ] **Level 5 — Human Review:** Verify behavior matches requirements above
@@ -119,6 +152,18 @@ Run in this order — do not proceed if a level fails:
 - [ ] [Specific, testable criterion]
 - [ ] [Specific, testable criterion]
 
+## Confidence Score: __/10
+
+- **Strengths:** [What is clear and well-understood]
+- **Uncertainties:** [What might change or is not fully known]
+- **Mitigations:** [How uncertainties will be handled]
+
+Scoring guide:
+- 10: Everything is clear, patterns exist, no unknowns
+- 7-9: Minor unknowns but mitigations identified
+- 4-6: Significant unknowns or missing patterns
+- 1-3: High risk, major assumptions unverified
+
 ## Notes for Executing Agent
 [Any important context, warnings, or decisions made during planning that the executing agent needs to know]
 ```
@@ -136,6 +181,13 @@ Before saving the draft, review the plan against these criteria:
 - [ ] No ambiguous requirements left unresolved
 - [ ] **Data audit complete:** All data sources audited per `.agents/guides/data-audit.md`, with all findings (null cases, value semantics, derived value propagation) documented in Context References and Gotchas
 - [ ] **Working references specified:** Every framework-specific pattern references a proven working implementation with extracted API calls, prop types, and data flow — not just "see file X"
+- [ ] **API validation specified:** Every task that creates/modifies an API endpoint includes Validation (required fields, limits, format) and Error UX (what the user sees on failure)
+- [ ] **Test coverage:** At least one task creates or updates tests — or a justification is provided for why tests are not applicable
+- [ ] **User preferences checked:** MEMORY.md was consulted for UI preferences (modal vs inline, keyboard shortcuts, component conventions) that affect the plan
+- [ ] **Confidence score justified:** Score is provided with specific strengths, uncertainties, and mitigations
+- [ ] **Git strategy specified:** Base branch and feature branch are defined in `## Git Strategy`
+- [ ] **Interaction matrix included:** If the feature involves interactive UI, the `## Interaction Matrix` section is filled out — or explicitly marked as N/A with justification
+- [ ] **Time-box on risky tasks:** Any task involving unfamiliar libraries, heuristic parsing, or known-complex behavior (auto-sizing, animation, real-time sync) has a Time-box with a fallback strategy
 
 ## Phase 7: Save Draft and Enter Review Loop
 
@@ -164,4 +216,4 @@ Before saving the draft, review the plan against these criteria:
 
 **Finalize:**
 1. Rename `.agents/plans/[feature-name].draft.md` → `.agents/plans/[feature-name].md` (overwrite if it already exists)
-2. Confirm: "✅ Plan saved to `.agents/plans/[feature-name].md`. Run `/hopla-git-commit` to commit it, then share with the team to execute with `/hopla-execute .agents/plans/[feature-name].md`."
+2. Confirm: "✅ Plan saved to `.agents/plans/[feature-name].md`. Run `/hopla-review-plan .agents/plans/[feature-name].md` to review it, then `/hopla-execute .agents/plans/[feature-name].md` to implement it."

package/files/commands/hopla-prime.md

@@ -2,6 +2,8 @@
 description: Load project context at the start of a session
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Get oriented in this project before doing any work.
 
 ## Step 1: Project Structure
@@ -53,6 +55,6 @@ Pending plans:
 - add-user-authentication.md ← ready to execute with /hopla-execute
 ```
 
-End with a sentence like: "All caught up — what are we working on today?" (adapt to the user's language).
+End with a sentence like: "All caught up — what are we working on today?"
 
 Do NOT use headers in the prose summary. Write it as natural, friendly prose, then the pending plans list if applicable.

package/files/commands/hopla-review-plan.md

@@ -3,6 +3,8 @@ description: Review a plan before execution — get a concise summary and approv
 argument-hint: "<plan-file-path>"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Review the implementation plan and give the executing developer a clear, concise summary before they commit to running it.
 
 ## Step 1: Read the Plan
@@ -11,7 +13,7 @@ Read `$1` entirely before doing anything else.
 
 ## Step 2: Present Executive Summary
 
-Do NOT reproduce the full plan. Instead, present a structured summary in the user's language:
+Do NOT reproduce the full plan. Instead, present a structured summary:
 
 **Plan: [Feature Name]**
 

package/files/commands/hopla-system-review.md

@@ -3,6 +3,8 @@ description: Analyze implementation against plan to find process improvements
 argument-hint: "<plan-file> <execution-report-file>"
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Perform a meta-level analysis of how well the implementation followed the plan. This is NOT code review — you're looking for bugs in the process, not the code.
 
 ## Inputs

package/files/commands/hopla-validate.md

@@ -0,0 +1,65 @@
+---
+description: Run the full validation pyramid on the current project
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+Run the full validation pyramid to verify project health. Use this command when iterating on a small fix, after a refactor, or anytime you need to re-run all validation steps without starting a full PIV loop.
+
+## Step 1: Load Project Context
+
+Read `CLAUDE.md` or `AGENTS.md` to find the project's validation commands (look for a "Development Commands" or "Testing" section).
+
+If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
+
+## Step 2: Run the Validation Pyramid
+
+Execute each level in order. **Do not skip levels. Do not proceed if a level fails — fix it first.**
+
+### Level 1 — Lint & Format
+
+Run the project's lint and format commands (e.g. `npm run lint`, `uv run ruff check .`).
+
+If issues are found:
+- Fix them automatically if the tool supports it (e.g. `--fix`)
+- Re-run to confirm clean
+
+### Level 2 — Type Check
+
+Run the project's type checker (e.g. `npm run typecheck`, `uv run mypy .`).
+
+Fix all type errors before continuing.
+
+### Level 3 — Unit Tests
+
+Run the project's test suite (e.g. `npm run test`, `uv run pytest`).
+
+If tests fail:
+- Investigate the root cause
+- Fix the code (not the tests, unless the test is wrong)
+- Re-run until all pass
+
+### Level 4 — Integration Tests
+
+Run integration tests if the project has them (e.g. `npm run test:e2e`).
+
+If not available, skip and note it in the report.
+
+## Step 3: Summary Report
+
+Provide a clear summary:
+
+```
+## Validation Report
+
+- Level 1 Lint & Format:  ✅ / ❌ [details]
+- Level 2 Type Check:     ✅ / ❌ [details]
+- Level 3 Unit Tests:     ✅ [X passed] / ❌ [X failed]
+- Level 4 Integration:    ✅ / ❌ / ⏭️ skipped
+
+**Overall: ✅ PASS / ❌ FAIL**
+```
+
+If everything passes, confirm the project is healthy.
+
+If anything failed and could not be fixed, list the remaining issues and suggest next steps.

package/files/skills/hopla-code-review/SKILL.md

@@ -3,6 +3,8 @@ name: hopla-code-review
 description: Performs a technical code review on recently changed files. Use when the user says "review the code", "code review", "check my code", "look for issues", or asks for feedback on their implementation.
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Perform a technical code review focused on finding real bugs and issues.
 
 ## Step 1: Load Context

package/files/skills/hopla-execution-report/SKILL.md

@@ -3,6 +3,8 @@ name: hopla-execution-report
 description: Generates an implementation report documenting what was built. Use when the user says "generate the report", "genera el reporte", "documenta lo implementado", "execution report", "document what was done", "write the implementation report", or after finishing a feature before committing.
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Review and document the implementation you just completed. Run this immediately after finishing a feature — before committing or starting the next task.
 
 ## Step 1: Gather Implementation Data

package/files/skills/hopla-git/SKILL.md

@@ -3,6 +3,8 @@ name: hopla-git
 description: Handles git operations: creating commits, making pull requests, pushing branches. Use when the user asks to commit, create a commit, save changes to git, make a PR, create a pull request, push the branch, or any git workflow action.
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Detect the user's intent and execute the appropriate git workflow.
 
 ## Intent Detection

package/files/skills/hopla-git/commit.md

@@ -1,5 +1,7 @@
 # Hopla Git Commit — Full Workflow
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Review the current git state and create an appropriate conventional commit.
 
 ## Step 1: Gather Context

package/files/skills/hopla-git/pr.md

@@ -1,5 +1,7 @@
 # Hopla Git PR — Full Workflow
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Create a Pull Request on GitHub for the current branch.
 
 ## Step 1: Gather Context
@@ -17,9 +19,23 @@ Read the following if they exist:
 
 ## Step 2: Determine Base Branch
 
-- If the user specified a base branch, use it
-- Otherwise default to `develop` (or `dev` if that's what the project uses)
-- If on `main` or `develop` directly, warn the user: "You're on `[branch]` — PRs should come from feature branches."
+**If the user specified a base branch**, use it.
+
+**Otherwise, infer from Git Flow branch naming:**
+
+| Current branch prefix | Base branch |
+|---|---|
+| `feature/*` | `develop` or `dev` |
+| `fix/*` | `develop` or `dev` |
+| `hotfix/*` | `main` |
+| `release/*` | `main` |
+
+To resolve `develop` vs `dev`: run `git branch -r` and look for `origin/develop` or `origin/dev`. Use whichever exists.
+
+**Guard rails:**
+- If the current branch is `main`, `master`, `develop`, or `dev` → stop and warn: "You're on `[branch]` — PRs should come from feature branches."
+- If the branch name doesn't match any Git Flow prefix → ask the user: "I can't determine the base branch from `[branch]`. Should this PR target `develop` or `main`?"
+- **Always show the resolved base branch in Step 5** so the user can catch mistakes before the PR is created.
 
 ## Step 3: Check Push Status
 
@@ -77,3 +93,38 @@ gh pr create --title "[title]" --body "[body]" --base [base-branch]
 After creating, show the PR URL to the user.
 
 **Never merge automatically** — the PR is for human review.
+
+## Step 7: Post-Merge Cleanup
+
+After the user confirms the PR was approved and merged on GitHub, run the cleanup workflow based on the branch type:
+
+### For all branch types:
+
+```bash
+git checkout [base-branch]
+git pull origin [base-branch]
+git branch -d [merged-branch]
+git push origin --delete [merged-branch] 2>/dev/null  # skip if GitHub already deleted it
+```
+
+### Additional steps for `hotfix/*` and `release/*`:
+
+These branches were merged to `main` but `develop` also needs the changes:
+
+```bash
+git checkout develop
+git pull origin develop
+git merge main
+git push origin develop
+```
+
+Then create a version tag:
+
+```bash
+git tag -a v[version] -m "Release [version]"
+git push origin v[version]
+```
+
+Ask the user for the version number before tagging.
+
+**Always confirm each destructive action** (branch deletion, tag creation) before executing.

package/files/skills/hopla-prime/SKILL.md

@@ -3,6 +3,8 @@ name: hopla-prime
 description: Orients Claude in a project at the start of a session. Use when the user says "orient yourself", "get oriented", "prime yourself", "what is this project", "load context", or asks Claude to familiarize itself with the codebase before starting work.
 ---
 
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 Get oriented in this project before doing any work.
 
 ## Step 1: Project Structure
@@ -54,6 +56,6 @@ Pending plans:
 - add-user-authentication.md ← ready to execute with /hopla-execute
 ```
 
-End with a sentence like: "All caught up — what are we working on today?" (adapt to the user's language).
+End with a sentence like: "All caught up — what are we working on today?"
 
 Do NOT use headers in the prose summary. Write it as natural, friendly prose, then the pending plans list if applicable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.4.5",
+  "version": "1.6.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {