@hopla/claude-setup 1.3.4 → 1.4.0

package/README.md

@@ -72,6 +72,8 @@ This system is built on two core concepts from the Agentic Coding Course:
 | **Global Rules** | Always-loaded context: language, git flow, tech defaults, autonomy rules | `~/.claude/CLAUDE.md` |
 | **On-Demand Context** | Task-specific guides loaded when needed (e.g. "how to add an API endpoint") | `.agents/guides/*.md` |
 | **Commands** | Reusable processes that tell the agent *how* to work | `~/.claude/commands/hopla-*.md` |
+| **Skills** | Auto-activate by semantic matching — no slash command needed | `~/.claude/skills/hopla-*/SKILL.md` |
+| **Hooks** | Run automatically before/after tool use for type checking and protection | `~/.claude/hooks/*.js` |
 
 The key insight: **commands inject on-demand context deterministically** — when you run `/hopla-plan-feature`, it automatically reads the relevant guide from `.agents/guides/` before planning.
 
@@ -112,6 +114,42 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 | `/hopla-execution-report` | Generate an implementation report for system review |
 | `/hopla-system-review` | Analyze implementation against plan to find process improvements |
 
+**`~/.claude/skills/`** — Auto-activate by semantic matching, no slash command needed:
+
+| Skill | Auto-activates when you say... |
+|---|---|
+| `hopla-git` | "commit this", "create a PR", "guarda los cambios" |
+| `hopla-prime` | "orient yourself", "ponte al día", "what is this project" |
+| `hopla-code-review` | "review the code", "code review", "analiza los cambios" |
+| `hopla-execution-report` | "generate the report", "genera el reporte", "document what was done" |
+
+**`~/.claude/hooks/`** — Run automatically before/after tool use (configured in `~/.claude/settings.json`):
+
+| Hook | Type | What it does |
+|---|---|---|
+| `tsc-check.js` | PostToolUse | Runs `tsc --noEmit` after file edits; feeds errors back to Claude |
+| `env-protect.js` | PreToolUse | Blocks reads/greps targeting `.env` files |
+| `session-prime.js` | SessionStart (opt-in) | Loads git context + CLAUDE.md summary at session start |
+
+**Installed layout:**
+
+```
+~/.claude/
+├── CLAUDE.md              ← Global rules
+├── commands/
+│   └── hopla-*.md         ← Slash commands (/hopla-prime, /hopla-execute, etc.)
+├── skills/
+│   ├── hopla-git/         ← Auto-activates for commit/PR requests
+│   ├── hopla-prime/       ← Auto-activates for orientation requests
+│   ├── hopla-code-review/ ← Auto-activates for review requests
+│   └── hopla-execution-report/ ← Auto-activates for report requests
+├── hooks/
+│   ├── tsc-check.js       ← TypeScript type checking after edits
+│   ├── env-protect.js     ← .env file protection
+│   └── session-prime.js   ← Session context loader (opt-in)
+└── settings.json          ← Permissions + hooks config (auto-updated)
+```
+
 ---
 
 ## Recommended Workflow
@@ -141,6 +179,8 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 /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.
+
 ---
 
 ## Command Chaining

package/cli.js

@@ -17,6 +17,8 @@ if (VERSION) {
 }
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
+const SKILLS_DIR = path.join(CLAUDE_DIR, "skills");
+const HOOKS_DIR = path.join(CLAUDE_DIR, "hooks");
 const FILES_DIR = path.join(import.meta.dirname, "files");
 
 const GREEN = "\x1b[32m";
@@ -226,6 +228,169 @@ async function install() {
     }
 
     await setupPermissions();
+    await installSkills();
+    await installHooks();
+}
+
+// Skills to install in planning mode (subset)
+const PLANNING_SKILLS = ["hopla-prime"];
+
+async function installSkills() {
+    const skillsSrcDir = path.join(FILES_DIR, "skills");
+    if (!fs.existsSync(skillsSrcDir)) return;
+
+    fs.mkdirSync(SKILLS_DIR, { recursive: true });
+
+    const skillDirs = fs.readdirSync(skillsSrcDir).filter((entry) => {
+        return fs.statSync(path.join(skillsSrcDir, entry)).isDirectory();
+    });
+
+    const skillsToInstall = PLANNING
+        ? skillDirs.filter((d) => PLANNING_SKILLS.includes(d))
+        : skillDirs;
+
+    if (skillsToInstall.length === 0) return;
+
+    log(`\n${CYAN}Installing skills...${RESET}`);
+    for (const skillName of skillsToInstall.sort()) {
+        const srcDir = path.join(skillsSrcDir, skillName);
+        const destDir = path.join(SKILLS_DIR, skillName);
+        fs.mkdirSync(destDir, { recursive: true });
+        for (const file of fs.readdirSync(srcDir).sort()) {
+            await installFile(
+                path.join(srcDir, file),
+                path.join(destDir, file),
+                `~/.claude/skills/${skillName}/${file}`
+            );
+        }
+    }
+
+    log(`\n${GREEN}${BOLD}Skills installed!${RESET} Auto-activate without a slash command:\n`);
+    for (const skillName of skillsToInstall.sort()) {
+        log(`  ${CYAN}${skillName}${RESET}`);
+    }
+}
+
+async function installHooks() {
+    const hooksSrcDir = path.join(FILES_DIR, "hooks");
+    if (!fs.existsSync(hooksSrcDir)) return;
+
+    const hookFiles = fs.readdirSync(hooksSrcDir).filter((f) => f.endsWith(".js"));
+    if (hookFiles.length === 0) return;
+
+    const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+
+    // Read existing settings
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        } catch {
+            // keep defaults
+        }
+    }
+
+    const existingHooks = settings.hooks || {};
+    const tscHookCmd = `${HOOKS_DIR}/tsc-check.js`;
+    const envHookCmd = `${HOOKS_DIR}/env-protect.js`;
+    const sessionHookCmd = `${HOOKS_DIR}/session-prime.js`;
+
+    // Check what's already configured
+    const postToolUseHooks = existingHooks.PostToolUse || [];
+    const preToolUseHooks = existingHooks.PreToolUse || [];
+    const sessionStartHooks = existingHooks.SessionStart || [];
+
+    const hasTsc = postToolUseHooks.some((h) =>
+        h.hooks?.some((hh) => hh.command === tscHookCmd)
+    );
+    const hasEnv = preToolUseHooks.some((h) =>
+        h.hooks?.some((hh) => hh.command === envHookCmd)
+    );
+    const hasSession = sessionStartHooks.some((h) =>
+        h.hooks?.some((hh) => hh.command === sessionHookCmd)
+    );
+
+    const toAdd = [];
+    if (!hasTsc) toAdd.push(`PostToolUse(Write|Edit|MultiEdit) → tsc-check.js`);
+    if (!hasEnv) toAdd.push(`PreToolUse(Read|Grep) → env-protect.js`);
+
+    log(`\n${CYAN}Configuring hooks...${RESET}`);
+
+    if (toAdd.length === 0 && hasSession) {
+        log(`${GREEN}✓${RESET}  Hooks already configured.\n`);
+        return;
+    }
+
+    if (toAdd.length > 0) {
+        log(`  The following hooks will be added to ~/.claude/settings.json:\n`);
+        for (const h of toAdd) {
+            log(`  ${CYAN}+${RESET}  ${h}`);
+        }
+    }
+
+    // Ask about session-prime separately (opt-in)
+    let installSessionPrime = false;
+    if (!hasSession) {
+        log(`\n  ${YELLOW}Optional:${RESET} session-prime.js auto-loads project context on session start.`);
+        installSessionPrime = await confirm(`  Enable session-prime hook? (y/N) `);
+    }
+
+    if (toAdd.length === 0 && !installSessionPrime) {
+        log(`  ${YELLOW}↷${RESET}  Skipped hooks — you can configure ~/.claude/settings.json manually\n`);
+        return;
+    }
+
+    const ok = toAdd.length > 0
+        ? await confirm(`\n  Install these hooks? (y/N) `)
+        : true;
+
+    if (!ok) {
+        log(`  ${YELLOW}↷${RESET}  Skipped hooks — you can configure ~/.claude/settings.json manually\n`);
+        return;
+    }
+
+    // Copy hook files
+    fs.mkdirSync(HOOKS_DIR, { recursive: true });
+    for (const file of hookFiles) {
+        await installFile(
+            path.join(hooksSrcDir, file),
+            path.join(HOOKS_DIR, file),
+            `~/.claude/hooks/${file}`
+        );
+        // Make executable
+        try {
+            fs.chmodSync(path.join(HOOKS_DIR, file), 0o755);
+        } catch {
+            // Non-critical
+        }
+    }
+
+    // Build updated hooks config
+    if (!settings.hooks) settings.hooks = {};
+
+    if (!hasTsc) {
+        if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+        settings.hooks.PostToolUse.push({
+            matcher: "Write|Edit|MultiEdit",
+            hooks: [{ type: "command", command: tscHookCmd }],
+        });
+    }
+    if (!hasEnv) {
+        if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+        settings.hooks.PreToolUse.push({
+            matcher: "Read|Grep",
+            hooks: [{ type: "command", command: envHookCmd }],
+        });
+    }
+    if (installSessionPrime && !hasSession) {
+        if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+        settings.hooks.SessionStart.push({
+            hooks: [{ type: "command", command: sessionHookCmd }],
+        });
+    }
+
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    log(`  ${GREEN}✓${RESET}  Hooks configured.\n`);
 }
 
 const HOPLA_PERMISSIONS = [

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

@@ -139,6 +139,16 @@ Before saving the draft, review the plan against these criteria:
 
 ## Phase 7: Save Draft and Enter Review Loop
 
+**Before saving, identify the target file:**
+
+1. List all files in `.agents/plans/` (both `*.draft.md` and `*.md`)
+2. Determine the target filename from the feature name derived in Phase 1: `[kebab-case-feature-name].draft.md`
+3. If a file with that name already exists → **overwrite it**
+4. If a file with a similar name exists (e.g. same feature, slight variation) → **overwrite it and confirm which file was updated**
+5. Never create versioned files (e.g. `-v2`, `-updated`, `-new`) — always update in place
+
+**Save and notify:**
+
 1. Save the plan to `.agents/plans/[kebab-case-feature-name].draft.md`
 2. Tell the user:
    > "Plan draft saved to `.agents/plans/[feature-name].draft.md` — open it in your editor and review it carefully. If you want changes, add comments like `<? change this >` anywhere in the file and tell me 'apply comments'. You can also request changes directly in the chat. When it's ready, say 'done' to create the final file."
@@ -147,10 +157,11 @@ Before saving the draft, review the plan against these criteria:
    - Any open questions or decisions that require human input before execution
 
 **Review loop:** Stay in this loop until the user finalizes:
-- If the user says **"apply comments"** → scan the draft for `<? ... >`, apply each one, remove the comment tags, update the file, report what changed
-- If the user requests changes in chat → apply directly to the draft, confirm what changed
+- If the user says **"apply comments"** → identify the active draft (the one saved in this session, or ask if unclear), scan it for `<? ... >`, apply each one, remove the comment tags, update the file, report what changed
+- If the user requests changes in chat → apply directly to the active draft, confirm the filename and what changed
+- If the user references a specific plan file (e.g. passes a path) → treat that file as the active draft
 - If the user says the plan is ready → proceed to finalize
 
 **Finalize:**
-1. Rename `.agents/plans/[feature-name].draft.md` → `.agents/plans/[feature-name].md`
+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`."

package/files/hooks/env-protect.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// PreToolUse hook: blocks reads/greps targeting .env files
+
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+
+    const toolCall = JSON.parse(Buffer.concat(chunks).toString());
+    const filePath = toolCall.tool_input?.file_path || toolCall.tool_input?.path || "";
+
+    if (filePath.includes(".env")) {
+        process.stderr.write(
+            `Access denied: Reading .env files is blocked to prevent accidental secret exposure. ` +
+            `If you need environment variable names, check the README or ask the user.\n`
+        );
+        process.exit(2);
+    }
+
+    process.exit(0);
+}
+
+main();

package/files/hooks/session-prime.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// SessionStart hook: provides initial project context when a session begins
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+function run(cmd) {
+    try {
+        return execSync(cmd, { cwd: process.cwd(), stdio: "pipe" }).toString().trim();
+    } catch {
+        return null;
+    }
+}
+
+async function main() {
+    const lines = [];
+
+    // Git context
+    const branch = run("git branch --show-current");
+    const log = run("git log --oneline -5");
+    const status = run("git status --short");
+
+    if (branch) {
+        lines.push(`Current branch: ${branch}`);
+    }
+    if (log) {
+        lines.push(`Recent commits:\n${log}`);
+    }
+    if (status) {
+        lines.push(`Uncommitted changes:\n${status}`);
+    } else if (branch) {
+        lines.push("Working tree is clean.");
+    }
+
+    // CLAUDE.md summary (first 20 lines)
+    const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+        const content = fs.readFileSync(claudeMdPath, "utf8").split("\n").slice(0, 20).join("\n");
+        lines.push(`Project rules (CLAUDE.md excerpt):\n${content}`);
+    }
+
+    if (lines.length > 0) {
+        process.stdout.write("=== Session Context ===\n" + lines.join("\n\n") + "\n======================\n");
+    }
+
+    process.exit(0);
+}
+
+main();

package/files/hooks/tsc-check.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// PostToolUse hook: runs tsc --noEmit after file edits and feeds errors back to Claude
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+
+    // If no tsconfig.json in cwd, exit silently (non-TS project)
+    const tsconfigPath = path.join(process.cwd(), "tsconfig.json");
+    if (!fs.existsSync(tsconfigPath)) {
+        process.exit(0);
+    }
+
+    let result;
+    try {
+        execSync("tsc --noEmit", { cwd: process.cwd(), stdio: "pipe" });
+        // No errors — exit silently
+        process.exit(0);
+    } catch (err) {
+        const output = (err.stdout || "").toString() + (err.stderr || "").toString();
+        if (output.trim()) {
+            process.stdout.write("TypeScript errors detected:\n" + output + "\n");
+        }
+        // Exit 0: PostToolUse hooks cannot block, but stdout is fed back to Claude
+        process.exit(0);
+    }
+}
+
+main();

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

@@ -0,0 +1,79 @@
+---
+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.
+---
+
+Perform a technical code review focused on finding real bugs and issues.
+
+## Step 1: Load Context
+
+Read `CLAUDE.md` or `AGENTS.md` to understand project standards and patterns.
+
+If `.agents/guides/` exists, read any guides relevant to the files being reviewed (e.g. `@.agents/guides/api-guide.md` when reviewing API changes). These guides define the expected patterns for specific task types.
+
+## Step 2: Identify Changed Files
+
+```bash
+git diff --stat HEAD
+git diff HEAD
+git ls-files --others --exclude-standard
+```
+
+Read each changed or new file in its entirety — not just the diff.
+
+## Step 3: Analyze for Issues
+
+For each changed file, look for:
+
+**1. Logic Errors**
+- Off-by-one errors, incorrect conditionals
+- Missing error handling, unhandled edge cases
+- Race conditions or async issues
+
+**2. Security Issues**
+- Exposed secrets or API keys
+- SQL/command injection vulnerabilities
+- Insecure data handling or missing input validation
+- XSS vulnerabilities (frontend)
+
+**3. Performance Problems**
+- Unnecessary re-renders (React)
+- N+1 queries or redundant API calls
+- Memory leaks
+
+**4. Code Quality**
+- DRY violations
+- Poor naming or overly complex functions
+- Missing TypeScript types or `any` usage
+
+**5. Pattern Adherence**
+- Follows project conventions from CLAUDE.md
+- Consistent with existing codebase style
+
+## Step 4: Verify Issues Are Real
+
+Before reporting, confirm each issue is legitimate:
+- Run relevant tests if applicable
+- Check if the pattern is intentional based on context
+
+## Step 5: Output Report
+
+Save to `.agents/code-reviews/[descriptive-name].md`
+
+**Format for each issue:**
+```
+severity: critical | high | medium | low
+file: path/to/file.ts
+line: 42
+issue: [one-line description]
+detail: [why this is a problem]
+suggestion: [how to fix it]
+```
+
+If no issues found: "Code review passed. No technical issues detected."
+
+**Rules:**
+- Be specific — line numbers, not vague complaints
+- Focus on real bugs, not style preferences (linting handles that)
+- Flag security issues as `critical`
+- Suggest fixes, don't just identify problems

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

@@ -0,0 +1,68 @@
+---
+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.
+---
+
+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
+
+```bash
+git diff HEAD --stat
+git diff HEAD
+git ls-files --others --exclude-standard
+```
+
+## Step 2: Generate Report
+
+Save to: `.agents/execution-reports/[feature-name].md`
+
+Use the following structure:
+
+---
+
+### Meta Information
+
+- **Plan file:** [path to the plan that guided this implementation]
+- **Files added:** [list with paths]
+- **Files modified:** [list with paths]
+- **Lines changed:** +X -Y
+
+### Validation Results
+
+- Syntax & Linting: ✓/✗ [details if failed]
+- Type Checking: ✓/✗ [details if failed]
+- Unit Tests: ✓/✗ [X passed, Y failed]
+- Integration Tests: ✓/✗ [X passed, Y failed]
+
+### What Went Well
+
+List specific things that worked smoothly:
+- [concrete examples]
+
+### Challenges Encountered
+
+List specific difficulties encountered:
+- [what was difficult and why]
+
+### Divergences from Plan
+
+For each divergence from the original plan:
+
+**[Divergence Title]**
+- **Planned:** [what the plan specified]
+- **Actual:** [what was implemented instead]
+- **Reason:** [why this divergence occurred]
+- **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
+
+### Skipped Items
+
+List anything from the plan that was not implemented:
+- [what was skipped] — Reason: [why]
+
+### Recommendations
+
+Based on this implementation, what should change for next time?
+- Plan command improvements: [suggestions]
+- Execute command improvements: [suggestions]
+- CLAUDE.md additions: [suggestions]

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

@@ -0,0 +1,24 @@
+---
+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.
+---
+
+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"):
+- 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"):
+- 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?"
+
+## File References
+
+The full step-by-step instructions for each workflow are in:
+- `~/.claude/skills/hopla-git/commit.md` — conventional commit with Git Flow awareness
+- `~/.claude/skills/hopla-git/pr.md` — GitHub PR creation with structured description
+
+Read the relevant file now and follow its instructions completely.

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

@@ -0,0 +1,57 @@
+# Hopla Git Commit — Full Workflow
+
+Review the current git state and create an appropriate conventional commit.
+
+## Step 1: Gather Context
+
+Run these commands to understand what changed:
+
+```bash
+git status
+git diff --staged
+git diff
+git log --oneline -5
+```
+
+## Step 2: Analyze Changes
+
+- Identify what was added, modified, or deleted
+- Determine the appropriate commit type: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`
+- Identify the scope if relevant (e.g., `auth`, `api`, `ui`)
+- Check current branch — confirm it follows Git Flow naming (`feature/`, `fix/`, `hotfix/`, `develop`, `dev`)
+
+## Step 3: Stage Files
+
+Stage only the relevant files for this commit (avoid `git add -A` unless all changes belong together):
+
+```bash
+git add <specific files>
+```
+
+## Step 4: Propose Commit
+
+Present the proposed commit message to the user **before executing**:
+
+> "Proposed commit:
+> `feat(products): add price filter to search endpoint`
+>
+> Files included: [list files]
+> Shall I proceed?"
+
+Wait for explicit approval before running `git commit`.
+
+## Step 5: Execute Commit
+
+Once approved, create the commit:
+
+```bash
+git commit -m "<type>(<scope>): <description>"
+```
+
+## Step 6: Push Reminder
+
+After committing, remind the user:
+
+> "Commit created locally. Do you want to push to `origin/<branch>`?"
+
+**Never push automatically** — wait for explicit confirmation.

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

@@ -0,0 +1,79 @@
+# Hopla Git PR — Full Workflow
+
+Create a Pull Request on GitHub for the current branch.
+
+## Step 1: Gather Context
+
+```bash
+git status
+git branch --show-current
+git log --oneline origin/$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | sed 's|.*/||' || echo 'develop')..HEAD
+git diff --stat origin/$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | sed 's|.*/||' || echo 'develop')..HEAD
+```
+
+Read the following if they exist:
+- The plan file in `.agents/plans/` related to this feature
+- `CLAUDE.md` — for project context
+
+## 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."
+
+## Step 3: Check Push Status
+
+```bash
+git status
+```
+
+If the branch hasn't been pushed yet:
+> "Branch not pushed yet. Push to origin first?"
+
+Wait for confirmation before pushing:
+```bash
+git push -u origin <branch>
+```
+
+## Step 4: Build PR Description
+
+Using the commits and plan context, draft:
+
+**Title:** `[type(scope)]: short description` — match the main commit or feature name, max 70 chars
+
+**Body:**
+```markdown
+## Summary
+- [What was built — 2-3 bullets max]
+
+## Changes
+- [Key files modified and why]
+
+## Test Plan
+- [ ] [How to verify this works]
+- [ ] [Edge cases to check]
+
+## Related
+- Plan: `.agents/plans/[feature-name].md` (if exists)
+```
+
+## Step 5: Propose and Confirm
+
+Show the proposed PR title and body to the user:
+> "Proposed PR:
+> Title: `[title]`
+> Base: `[base branch]`
+> [body preview]
+> Shall I create it?"
+
+Wait for explicit approval before creating.
+
+## Step 6: Create PR
+
+```bash
+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.

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

@@ -0,0 +1,59 @@
+---
+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.
+---
+
+Get oriented in this project before doing any work.
+
+## Step 1: Project Structure
+
+Use the Glob tool to list project files (up to 60):
+- Pattern: `**/*` with head_limit: 60
+
+Use the Glob tool to find key config files:
+- `**/CLAUDE.md`
+- `**/AGENTS.md`
+- `**/README.md`
+
+## Step 2: Read Key Files
+
+Read in this order:
+1. `CLAUDE.md` or `AGENTS.md` at project root (project-specific rules)
+2. `README.md` (project overview)
+3. `package.json` or `pyproject.toml` (dependencies and scripts)
+
+## Step 3: Understand Git State
+
+```bash
+git branch --show-current
+git log --oneline -10
+git status
+```
+
+## Step 4: Check Pending Work
+
+Use the Glob tool to check for pending plans:
+- Pattern: `.agents/plans/*.md`
+
+If `.agents/plans/` exists, identify:
+- `.draft.md` files — unfinished drafts waiting for review
+- `.md` files (without `.draft`) — finalized plans ready to execute
+
+## Step 5: Summary Report
+
+Write a short, conversational message addressed directly to the user. Mention:
+- What the project is and what it does
+- The current branch and what it's for
+- Whether there are uncommitted changes or pending work
+- The command to start the project (if available)
+
+If there are pending plans, list them clearly after the prose summary:
+```
+Pending plans:
+- inventory-page.draft.md ← draft, not finalized yet
+- 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.
+
+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.3.4",
+  "version": "1.4.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {