@hopla/claude-setup 1.4.4 → 1.5.0

package/README.md

@@ -226,6 +226,16 @@ Commands are modular — the output of one becomes the input of the next. Some c
 
 ---
 
+## 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/cli.js

@@ -72,17 +72,38 @@ function removeFile(dest, label) {
 async function uninstall() {
     log(`\n${BOLD}@hopla/claude-setup${RESET} — Uninstall\n`);
 
-    const commandFiles = fs.readdirSync(path.join(FILES_DIR, "commands"));
-    const filesToRemove = [
-        { dest: path.join(CLAUDE_DIR, "CLAUDE.md"), label: "~/.claude/CLAUDE.md" },
-        ...commandFiles.map((file) => ({
+    const srcEntries = fs.readdirSync(path.join(FILES_DIR, "commands"));
+    const srcFiles = srcEntries.filter((f) =>
+        fs.statSync(path.join(FILES_DIR, "commands", f)).isFile()
+    );
+    const srcDirs = srcEntries.filter((f) =>
+        fs.statSync(path.join(FILES_DIR, "commands", f)).isDirectory()
+    );
+
+    const itemsToRemove = [
+        { dest: path.join(CLAUDE_DIR, "CLAUDE.md"), label: "~/.claude/CLAUDE.md", isDir: false },
+        ...srcFiles.map((file) => ({
             dest: path.join(COMMANDS_DIR, file),
             label: `~/.claude/commands/${file}`,
+            isDir: false,
+        })),
+        ...srcDirs.map((dir) => ({
+            dest: path.join(COMMANDS_DIR, dir),
+            label: `~/.claude/commands/${dir}/`,
+            isDir: true,
         })),
     ];
 
-    log(`The following files will be removed:`);
-    for (const { label } of filesToRemove) {
+    // Also remove skills and hooks installed by hopla
+    if (fs.existsSync(SKILLS_DIR)) {
+        itemsToRemove.push({ dest: SKILLS_DIR, label: "~/.claude/skills/", isDir: true });
+    }
+    if (fs.existsSync(HOOKS_DIR)) {
+        itemsToRemove.push({ dest: HOOKS_DIR, label: "~/.claude/hooks/", isDir: true });
+    }
+
+    log(`The following will be removed:`);
+    for (const { label } of itemsToRemove) {
         log(`  ${RED}✕${RESET}  ${label}`);
     }
 
@@ -93,40 +114,34 @@ async function uninstall() {
     }
 
     log("");
-    for (const { dest, label } of filesToRemove) {
-        removeFile(dest, label);
+    for (const { dest, label, isDir } of itemsToRemove) {
+        if (fs.existsSync(dest)) {
+            fs.rmSync(dest, { recursive: isDir });
+            log(`  ${RED}✕${RESET}  Removed: ${label}`);
+        } else {
+            log(`  ${YELLOW}↷${RESET}  Not found: ${label}`);
+        }
     }
 
     log(`\n${GREEN}${BOLD}Done!${RESET} Files removed.\n`);
 }
 
-const LEGACY_FILES = [
-    "code-review-fix.md",
-    "code-review.md",
-    "commit.md",
-    "create-prd.md",
-    "execute.md",
-    "execution-report.md",
-    "plan-feature.md",
-    "prime.md",
-    "system-review.md",
-    "hopla-lang.md",
-    "hopla-commit.md",
-];
-
-function removeLegacyFiles() {
+function removeStaleCommands(currentCommandFiles) {
+    if (!fs.existsSync(COMMANDS_DIR)) return;
+    const currentSet = new Set(currentCommandFiles);
     const removed = [];
-    for (const file of LEGACY_FILES) {
-        const dest = path.join(COMMANDS_DIR, file);
-        if (fs.existsSync(dest)) {
-            fs.rmSync(dest);
+    for (const file of fs.readdirSync(COMMANDS_DIR)) {
+        const filePath = path.join(COMMANDS_DIR, file);
+        if (!fs.statSync(filePath).isFile()) continue;
+        if (file.startsWith("hopla-") && !currentSet.has(file)) {
+            fs.rmSync(filePath);
             removed.push(file);
         }
     }
     if (removed.length > 0) {
-        log(`${CYAN}Cleaning up legacy commands...${RESET}`);
+        log(`${CYAN}Removing stale commands from previous versions...${RESET}`);
         for (const file of removed) {
-            log(`  ${YELLOW}↷${RESET}  Removed legacy: ~/.claude/commands/${file}`);
+            log(`  ${YELLOW}↷${RESET}  Removed: ~/.claude/commands/${file}`);
         }
         log("");
     }
@@ -142,25 +157,6 @@ const PLANNING_COMMANDS = [
     "hopla-git-pr.md",
 ];
 
-function removeExecutionCommands() {
-    const planningSet = new Set(PLANNING_COMMANDS);
-    const removed = [];
-    if (!fs.existsSync(COMMANDS_DIR)) return;
-    for (const file of fs.readdirSync(COMMANDS_DIR)) {
-        if (file.startsWith("hopla-") && !planningSet.has(file)) {
-            fs.rmSync(path.join(COMMANDS_DIR, file));
-            removed.push(file);
-        }
-    }
-    if (removed.length > 0) {
-        log(`${CYAN}Removing execution commands (planning mode)...${RESET}`);
-        for (const file of removed) {
-            log(`  ${RED}✕${RESET}  Removed: ~/.claude/commands/${file}`);
-        }
-        log("");
-    }
-}
-
 async function install() {
     const modeLabel = PLANNING ? "Planning Mode (Robert)" : "Full Install";
     log(`\n${BOLD}@hopla/claude-setup${RESET} — Agentic Coding System ${CYAN}[${modeLabel}]${RESET}\n`);
@@ -169,20 +165,7 @@ async function install() {
     fs.mkdirSync(CLAUDE_DIR, { recursive: true });
     fs.mkdirSync(COMMANDS_DIR, { recursive: true });
 
-    // Remove old non-prefixed commands from previous versions
-    removeLegacyFiles();
-
-    // In planning mode, remove any execution commands left from a previous full install
-    if (PLANNING) removeExecutionCommands();
-
-    log(`${CYAN}Installing global rules...${RESET}`);
-    await installFile(
-        path.join(FILES_DIR, "CLAUDE.md"),
-        path.join(CLAUDE_DIR, "CLAUDE.md"),
-        "~/.claude/CLAUDE.md"
-    );
-
-    log(`\n${CYAN}Installing commands...${RESET}`);
+    // Determine which command files will be installed
     const allCommandEntries = fs.readdirSync(path.join(FILES_DIR, "commands"));
     const allCommandFiles = allCommandEntries.filter((f) => {
         const stat = fs.statSync(path.join(FILES_DIR, "commands", f));
@@ -195,6 +178,18 @@ async function install() {
     const commandFiles = PLANNING
         ? allCommandFiles.filter((f) => PLANNING_COMMANDS.includes(f))
         : allCommandFiles;
+
+    // Remove stale hopla-* commands not in the current version
+    removeStaleCommands(commandFiles);
+
+    log(`${CYAN}Installing global rules...${RESET}`);
+    await installFile(
+        path.join(FILES_DIR, "CLAUDE.md"),
+        path.join(CLAUDE_DIR, "CLAUDE.md"),
+        "~/.claude/CLAUDE.md"
+    );
+
+    log(`\n${CYAN}Installing commands...${RESET}`);
     for (const file of commandFiles.sort()) {
         await installFile(
             path.join(FILES_DIR, "commands", file),

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

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

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,13 +42,22 @@ 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]`)"
@@ -114,7 +125,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 +162,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]
@@ -153,5 +181,4 @@ Provide a summary of what was done:
 
 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
+2. Run `/hopla-git-commit` once everything is approved

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

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

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,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/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:
 
@@ -99,17 +102,26 @@ Key files the executing agent must read before starting:
 - **Gotcha:** [Known pitfall or constraint] — or `N/A`
 - **Validate:** [Exact command or check to confirm this task is done correctly]
 
+#### 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]
 
 [Continue for all tasks...]
 
+## 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.
+
 ## 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 +131,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 +160,10 @@ 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
 
 ## Phase 7: Save Draft and Enter Review Loop
 

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: "Listo para continuar — ¿por dónde empezamos?" or "All caught up — what are we working on today?" depending on the language the user writes in.
+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]**
 
@@ -41,9 +43,8 @@ Do NOT reproduce the full plan. Instead, present a structured summary in the use
 
 ## Step 3: Ask for Approval
 
-After the summary, ask:
-> "¿Todo claro? Puedes aprobar para ejecutar, pedir cambios, o hacer preguntas sobre alguna tarea."
-> (or in English if the conversation is in English)
+After the summary, ask (in the user's language):
+> "All clear? You can approve to execute, request changes, or ask questions about any task."
 
 **Review loop:**
 - If the user has questions → answer them based on the plan content

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
@@ -10,6 +12,22 @@ Perform a meta-level analysis of how well the implementation followed the plan.
 - **$1** — Path to the structured plan file
 - **$2** — Path to the execution report file
 
+## Step 0: Check for Existing Review
+
+Before doing anything else, check if a system review already exists for this plan:
+
+```bash
+ls .agents/system-reviews/
+```
+
+Look for a file that matches the feature name derived from **$1** (the plan filename). If a matching review exists:
+- Skip Steps 1–6
+- Go directly to **Step 7** to archive the plan
+
+If no matching review exists, continue with Step 1.
+
+---
+
 ## Step 1: Load All Context
 
 Read these four artifacts in order:
@@ -137,3 +155,15 @@ After the analysis, use this to prioritize actions:
 | Same manual step done 3+ times | Create a new command |
 | Plan was ambiguous in the same spot twice | Update plan-feature command |
 | First time seeing this issue | Note it, don't over-engineer yet |
+
+## Step 7: Archive the Plan
+
+Move the completed plan to the archive folder:
+
+```bash
+mkdir -p .agents/plans/done
+mv "$1" .agents/plans/done/
+```
+
+Then notify the user:
+> "✅ System review saved to `.agents/system-reviews/[feature]-review.md`. Plan archived to `.agents/plans/done/[plan-name].md` — the active plans folder is now clean."

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

@@ -1,8 +1,10 @@
 ---
 name: hopla-code-review
-description: Performs a technical code review on recently changed files. Use when the user says "review the code", "revisar el código", "code review", "analiza los cambios", "check my code", "revisa mi código", "look for issues", or asks for feedback on their implementation.
+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,17 +3,19 @@ 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
 
-**If the user wants to commit** (keywords: "commit", "comitea", "guarda los cambios", "save changes", "crear commit", "hacer commit"):
+**If the user wants to commit** (keywords: "commit", "save changes", "create commit"):
 - Read and follow the instructions in `commit.md` (located in the same directory as this skill)
 
-**If the user wants to create a PR or push** (keywords: "PR", "pull request", "crea un PR", "abre un PR", "push", "merge request"):
+**If the user wants to create a PR or push** (keywords: "PR", "pull request", "push", "merge request"):
 - Read and follow the instructions in `pr.md` (located in the same directory as this skill)
 
-**If unclear**, ask the user one short question: "¿Commit o Pull Request?" / "Commit or Pull Request?"
+**If unclear**, ask the user one short question: "Commit or Pull Request?"
 
 ## File References
 

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

@@ -1,8 +1,10 @@
 ---
 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", "ponte al día", "qué es este proyecto", "what is this project", "load context", or asks Claude to familiarize itself with the codebase before starting work.
+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: "Listo para continuar — ¿por dónde empezamos?" or "All caught up — what are we working on today?" depending on the language the user writes in.
+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.4",
+  "version": "1.5.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {