@hopla/claude-setup 1.12.0 → 1.14.0

package/commands/execute.md

@@ -29,6 +29,13 @@ Verify that the plan's documented assumptions still hold. **You are not re-audit
 
 See `.agents/guides/data-audit.md` for detailed criteria on what to check.
 
+**Concrete verification:** For each table or API endpoint mentioned in the plan's tasks, run ONE verification command before writing code. Examples:
+- Schema: `grep -n 'CREATE TABLE\|ALTER.*tablename' migrations/*.sql | tail -3`
+- API route: Read the route file and confirm the endpoint signature
+- Component: Read the component and confirm its props interface
+
+If ANY assumption from the plan doesn't match current code, file a Blocker Report immediately. Do not proceed with tasks that depend on incorrect assumptions.
+
 If a discrepancy is found, stop immediately and file a Blocker Report below. You may continue with tasks that are not blocked by the discrepancy.
 
 #### Blocker Report
@@ -60,10 +67,12 @@ 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]`)"
+Check the current branch and determine the appropriate action:
 - **If on a `feature/`, `fix/`, or `hotfix/` branch** — proceed
+- **If on `develop`/`dev`** — ask: "You're on `develop`. Should I create a feature branch first? (recommended: `feature/[plan-name]`)"
+- **If on `main` or `master`** — check if `develop`/`dev` exists:
+  - If `develop`/`dev` exists: warn "You're on `main` but `develop` exists. Switch to `develop` first, or create a feature branch from `main` if this is a hotfix."
+  - If NO `develop`/`dev` exists (GitHub Flow project): ask "You're on `main` (no develop branch detected). Should I create a feature branch? (recommended: `feature/[plan-name]`)"
 - **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?"
 
@@ -98,6 +107,7 @@ Work through each task in the plan sequentially. For each task:
 **Git strategy:**
 - **Plans with 1–7 tasks:** Do not commit after individual tasks. Keep all changes staged but uncommitted until the full plan passes validation (Step 5). This allows a clean revert if later tasks fail.
 - **Plans with 8+ tasks (or plans with `## Phase Boundaries`):** Commit at each phase boundary defined in the plan. Run Level 1–2 validation (lint + types) before each intermediate commit. Use commit message format: `feat(<scope>): <feature> — phase N of M`. This prevents losing work on large implementations if later phases fail.
+     For plans with 8+ tasks, the **first intermediate commit** should happen after the first 3-4 tasks pass validation — do not wait until a full phase boundary if one isn't defined. Losing work on large implementations was a recurring problem when commits were deferred too long.
 
 **Pause and report if, during implementation:**
 - A task is ambiguous or has multiple valid implementations
@@ -107,6 +117,15 @@ Work through each task in the plan sequentially. For each task:
 
 Do not improvise silently. When in doubt, stop and ask.
 
+### Destructive Command Guard
+
+**NEVER** run destructive database or state commands during plan execution:
+- `db:reset`, `db:push --force`, `DROP TABLE`, `DELETE FROM` without WHERE
+- `rm -rf` on data directories
+- `git reset --hard`, `git clean -fd`
+
+If a migration fails or data needs to be reset, **stop and report to the user**. The cost of pausing is low; the cost of data loss is catastrophic. This rule exists because a `db:reset` during execution caused complete local data loss in a past implementation.
+
 ### Scope Guard
 
 If the user requests changes that are NOT in the plan during execution:

package/commands/guide.md

@@ -1,3 +1,9 @@
+---
+description: 4D Framework guide for non-technical users working with AI coding assistants
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
 # HOPLA Guide for Non-Technical Users
 
 > A guided framework for working effectively with your AI coding assistant.

package/commands/init-project.md

@@ -427,18 +427,20 @@ Create the following directories (with `.gitkeep` where needed):
 
 ```
 .agents/
-├── plans/          <- /hopla-plan-feature saves here (commit these)
-├── guides/         <- on-demand reference guides (commit these)
-├── execution-reports/   <- /hopla-execution-report saves here (do NOT commit)
-├── code-reviews/        <- /hopla-code-review saves here (do NOT commit)
-└── system-reviews/      <- /hopla-system-review saves here (do NOT commit)
+├── plans/               <- /hopla-plan-feature saves here (commit)
+│   ├── done/            <- /hopla-system-review archives completed plans here (commit)
+│   └── backlog/         <- /hopla-execute Scope Guard defers ideas here (commit)
+├── specs/               <- brainstorm skill saves design docs here (commit)
+├── guides/              <- on-demand reference guides (commit)
+├── rca/                 <- /hopla-rca saves root cause analysis docs here (commit)
+├── execution-reports/   <- /hopla-execution-report saves here (commit — needed for cross-session learning)
+├── system-reviews/      <- /hopla-system-review saves here (commit — needed for feedback loop)
+└── code-reviews/        <- /hopla-code-review saves here (do NOT commit — ephemeral, consumed by code-review-fix)
 ```
 
 Add to `.gitignore` (create if it doesn't exist):
 ```
-.agents/execution-reports/
 .agents/code-reviews/
-.agents/system-reviews/
 ```
 
 ## Step 7: Create .claude/commands/ (optional but recommended)

package/commands/plan-feature.md

@@ -28,6 +28,7 @@ Read the following to understand the project:
 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)
+6. `.agents/execution-reports/` — if this directory exists, scan recent reports (last 3-5) for technical patterns discovered and gotchas relevant to the feature being planned. These contain real-world learnings from previous implementations that prevent re-discovering known issues.
 
 Then run:
 
@@ -52,6 +53,15 @@ Use the Grep tool to find relevant files (pattern: relevant keyword, case-insens
 
 Read the key files in their entirety — not just the parts that seem relevant.
 
+### Assumption verification (required)
+
+For each existing table, API endpoint, or component the plan will modify, verify the current state during planning — do not defer to execution:
+- **Database/schema:** Read the most recent migration or schema definition. Confirm column names, types, and constraints match your assumptions.
+- **API endpoints:** Read the actual route handler. Confirm the request/response shape matches your assumptions.
+- **Components:** Read the component file. Confirm props, state, and data flow match your assumptions.
+
+Document verified assumptions in the plan's **Context References** with the exact file and line number. This prevents the #1 cause of mid-implementation redesigns: plans that assumed a field name, type, or constraint that didn't match reality.
+
 ### Data audit (required for features that consume existing data)
 
 Follow the full checklist in `.agents/guides/data-audit.md`.
@@ -76,6 +86,10 @@ Based on research, define:
 - **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.
 - **Reuse context analysis:** When a new view reuses an existing component in a different context (e.g., a list component in a "history" view vs. an "active" view), the plan MUST list what's different about the new context's requirements: different columns, different data filters, different interactions, different toolbar layout. Missed context differences caused 40%+ of unplanned work in past implementations.
 - **Multi-phase plan guidance:** For features requiring 3+ phases, create an architectural plan (`backlog/NN-feature.md`) with schema, phase boundaries, and target architecture. When executing each phase, create a standalone plan (`phase-NX-description.md`) with full task-level detail following this template. The architectural plan is the spec; phase plans are the execution instructions. Each phase should have its own feature branch and PR.
+- **API surface enumeration (security/access control plans):** When the plan modifies access control, authorization, or data visibility, enumerate ALL API surfaces that serve the same data — REST endpoints, WebSocket handlers, Durable Object methods, and any other data paths. Each surface must be updated consistently. In past implementations, updating only the WebSocket path while missing the parallel REST endpoint caused a security gap that was only caught by code review. Add a task for each surface, not just the primary one.
+- **Role access matrix:** For features involving multiple user roles or multi-tenant access (admin, member, viewer, buyer, external user), define a matrix: what data does each role see? What endpoints does each role call? What filters apply per role? In past implementations, plans that didn't specify role-level access had authorization bugs discovered only during code review.
+- **External integration buffer:** If the feature integrates an external API or third-party service, budget 2x the estimated time. Document: do we have working test credentials? Is the SDK tested in our runtime (Workers, Node, edge, etc.)? Are there known deprecations or version constraints? External integrations consistently took 2-3x longer than planned in past implementations.
+- **UI iteration budget:** For features with significant UI (new pages, complex forms, interactive grids), note that UI specifications are provisional — expect 30-50% additional work for visual refinement based on user feedback. Specify what "good enough for v1" looks like vs. future polish. This prevents scope creep from being classified as plan failure.
 
 ## Phase 5: Generate the Plan
 
@@ -216,6 +230,8 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **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
 - [ ] **Plan size checked:** If >8 tasks, phase boundaries are defined with intermediate commit points. If >12 tasks, split justification is provided or phases are created.
 - [ ] **Likely follow-ups listed:** If the Out of Scope section has items, the Likely Follow-ups section is populated with naturally adjacent work the user may request
+- [ ] **API surface enumeration (if security/access plan):** All parallel API surfaces (REST, WebSocket, DO) that serve the same data are listed with a task for each
+- [ ] **N+1 query check:** For every task that writes database queries or API calls, verify: is any call inside a loop? Could it be batched? Are there duplicate existence checks before mutations? N+1 queries were found in 5 of 13 recent implementations.
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/commands/rca.md

@@ -1,6 +1,11 @@
-# Root Cause Analysis
+---
+description: Investigate a bug or issue and produce a structured RCA document
+argument-hint: "<issue-description-or-github-url>"
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
 
-> Investigate a bug or issue and produce a structured RCA document.
+# Root Cause Analysis
 
 > 💡 **Tip**: Use Extended Thinking mode for complex bugs with multiple possible causes.
 

package/global-rules.md

@@ -24,6 +24,7 @@
 ## 3. Behavior & Autonomy
 
 **Always ask before:**
+
 - Running `git commit`
 - Running `git push`
 - Installing new dependencies (`npm install <pkg>`, `pip install <pkg>`, etc.)
@@ -31,59 +32,33 @@
 - Any destructive or hard-to-reverse operation
 
 **Proactively suggest commits** at logical save points:
+
 - After completing a feature or fix
 - Before starting a risky refactor
 - After passing all validation checks
 - Explain WHY it's a good moment to commit so the team understands
 
 **Never:**
+
 - Auto-commit or auto-push without explicit approval
 - Skip validation steps to save time
 - Add features, refactors, or improvements beyond what was asked
 
 ---
 
-## 4. Git Workflow (Git Flow)
-
-### Branch Strategy
-- `main` → production only, never commit directly
-- `develop` / `dev` → active development branch
-- Feature branches: `feature/short-description`
-- Bug fix branches: `fix/short-description`
-- Hotfix branches: `hotfix/short-description`
-
-### Commit Format — Conventional Commits
-```
-<type>(<optional scope>): <short description>
-
-[optional body]
-```
-
-**Types:**
-- `feat:` — new feature
-- `fix:` — bug fix
-- `refactor:` — code restructure without behavior change
-- `docs:` — documentation only
-- `test:` — adding or fixing tests
-- `chore:` — build, config, dependencies
-- `style:` — formatting, no logic change
-
-**Examples:**
-```
-feat(auth): add JWT token validation
-fix(api): handle null response from products endpoint
-chore: update dependencies to latest versions
-```
-
-### When to Suggest a Commit
-Explain in plain language when suggesting a commit, adapting to the user's language, e.g.:
-> "This would be a good moment to commit — we finished feature X and all tests pass. Should we commit before continuing?"
+## 4. Git Workflow
+
+Follow **Conventional Commits** (`type(scope): description`). Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`.
+
+Branch strategy (GitHub Flow vs Git Flow) is **auto-detected** by the git skill based on whether `origin/develop` or `origin/dev` exists. See the git skill for full details.
+
+When suggesting a commit, explain in plain language why it's a good moment, adapting to the user's language.
 
 ---
 
 ## 5. Code Quality
 
-- Validate before considering anything done (lint → types → tests)
+- Validate before declaring done (lint → types → tests). The verify skill enforces this at completion.
 - Write tests alongside implementation, not after
 - Flag security issues immediately — never leave them for later
 - If the same validation failure repeats, signal it as a system improvement opportunity
@@ -93,11 +68,13 @@ Explain in plain language when suggesting a commit, adapting to the user's langu
 ## 📋 Context Management
 
 ### Three levels of CLAUDE.md
+
 - **Machine-level** (`~/.claude/CLAUDE.md`): These global rules — apply to all projects
 - **Project-level** (`CLAUDE.md` at repo root): Shared with team via git — project-specific rules
 - **Local-level** (`CLAUDE.local.md`): Personal overrides — NOT committed to git
 
 ### Context control
+
 - Use `@filename` to include specific files in context (works in chat and inside CLAUDE.md)
 - Use `/compact` between related tasks (preserves learned knowledge)
 - Use `/clear` between unrelated tasks (full reset)
@@ -116,19 +93,10 @@ Explain in plain language when suggesting a commit, adapting to the user's langu
 
 ---
 
-## 🛠️ Available HOPLA Commands
+## 🛠️ HOPLA Skills
+
+HOPLA skills are auto-triggered based on context — no slash command needed. The session-prime hook lists available skills at the start of each session.
+
 When a skill applies to your current task, you MUST use it. Check available skills before responding.
 
-### Workflow: Plan → Implement → Validate
-1. `/hopla-plan-feature` — Research codebase and create implementation plan
-2. `/hopla-review-plan` — Review plan before execution
-3. `/hopla-execute` — Execute plan with validation
-4. `/hopla-validate` — Run full validation pyramid
-5. `/hopla-git-commit` — Create conventional commit
-6. `/hopla-git-pr` — Create GitHub PR
-
-### Other commands
-- `/hopla-create-prd` — Create or update Product Requirements Document
-- `/hopla-init-project` — Initialize project with CLAUDE.md and .agents/ structure
-- `/hopla-code-review-fix` — Fix issues from code review report
-- `/hopla-system-review` — Analyze plan vs execution for process improvements
+Use the `plan-feature` command to start the full Plan → Implement → Validate workflow.

package/hooks/session-prime.js

@@ -13,6 +13,38 @@ function run(cmd) {
     }
 }
 
+function discoverSkills() {
+    // Try plugin context first: ../skills/ relative to this script
+    const hookDir = import.meta.dirname;
+    const skillsDir = path.join(hookDir, "..", "skills");
+
+    if (!fs.existsSync(skillsDir)) {
+        return null;
+    }
+
+    const skills = [];
+    for (const entry of fs.readdirSync(skillsDir).sort()) {
+        const skillDir = path.join(skillsDir, entry);
+        if (!fs.statSync(skillDir).isDirectory()) continue;
+
+        const skillFile = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillFile)) continue;
+
+        // Extract description from SKILL.md frontmatter
+        const content = fs.readFileSync(skillFile, "utf8");
+        const descMatch = content.match(/^description:\s*"?(.+?)"?\s*$/m);
+        if (descMatch) {
+            // Truncate to first sentence for brevity
+            const desc = descMatch[1].split(".")[0];
+            skills.push(`- ${entry}: ${desc}`);
+        } else {
+            skills.push(`- ${entry}`);
+        }
+    }
+
+    return skills.length > 0 ? skills : null;
+}
+
 async function main() {
     const lines = [];
 
@@ -40,18 +72,13 @@ async function main() {
         lines.push(`Project rules (CLAUDE.md excerpt):\n${content}`);
     }
 
-    // Available skills reminder
-    lines.push(`📦 HOPLA Skills Available:
-- prime: Project orientation (trigger: "orient", "get context", "load project")
-- git: Git operations (trigger: "commit", "PR", "push")
-- code-review: Code review (trigger: "review code", "code review")
-- execution-report: Post-implementation docs (trigger: "generate report")
-- verify: Completion verification (trigger: any "done"/"listo"/"finished" claim)
-- brainstorm: Design exploration (trigger: "new feature", "brainstorm", "explore options")
-- debug: Systematic debugging (trigger: "bug", "error", "debug")
-- tdd: Test-driven development (trigger: implementing with tests)
-
-⚠️ If a skill applies to the current task, you MUST use it.`);
+    // Auto-discover available skills
+    const skills = discoverSkills();
+    if (skills) {
+        lines.push(`📦 HOPLA Skills Available:\n${skills.join("\n")}\n\n⚠️ If a skill applies to the current task, you MUST use it.`);
+    } else {
+        lines.push(`📦 HOPLA skills are available. Check your session's skill list for details.\n\n⚠️ If a skill applies to the current task, you MUST use it.`);
+    }
 
     if (lines.length > 0) {
         process.stdout.write(lines.join("\n\n"));

package/package.json

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

package/skills/brainstorm/SKILL.md

@@ -87,3 +87,8 @@ Present the design document for user review.
 - Always ground proposals in the existing codebase (not abstract theory)
 - If the feature is trivial (< 30 minutes of work), skip the full process — just confirm approach and proceed
 - In planning mode (non-technical users): focus on product decisions, not technical details
+
+## Integration
+
+- If the user hasn't defined requirements yet, suggest: "Before brainstorming, consider running `/hopla-create-prd` to define the product requirements. This gives us clearer constraints to design against."
+- If the user is brainstorming a bug fix rather than a new feature, suggest: "This sounds like a bug rather than a new feature. Consider running the `debug` skill for systematic root cause analysis instead."

package/skills/code-review/SKILL.md

@@ -37,6 +37,7 @@ For each changed file, look for:
 - Stale closures — callbacks passed to imperative APIs (grids, charts, maps) that capture stale state instead of using refs or stable references
 - Unhandled promise rejections — `.then()` without `.catch()`, async calls without `try/catch` in non-void contexts
 - Side effects inside JSX render — mutations of arrays/objects inside `.map()` in JSX (breaks React strict mode, causes double-execution bugs)
+- Stale dependency arrays — for every new `useState`/`useRef` variable introduced in the diff, verify it appears in the dependency arrays of `useEffect`, `useCallback`, or `useMemo` that reference it. Missing deps cause stale closures — this was the #1 React bug category across 28 implementations
 
 **2. Security Issues**
 - Exposed secrets or API keys
@@ -44,10 +45,11 @@ For each changed file, look for:
 - Missing input validation on API endpoints — required fields, format constraints (regex, length), payload size limits
 - Insecure data handling — raw user input in queries, responses exposing internal data or stack traces
 - XSS vulnerabilities (frontend)
+- Multi-user authorization context — for multi-tenant apps, verify each endpoint filters by the correct context (e.g., active org vs personal org, admin vs viewer). Check that middleware/auth guards match the intended audience for each route
 
 **3. Performance Problems**
 - Unnecessary re-renders (React)
-- N+1 queries or redundant API calls
+- N+1 queries — database queries or API calls inside loops (`for`, `.map`, `.forEach`), duplicate existence checks before mutations, sequential operations that could use `Promise.all()` or batch SQL. This was found in 5 of 13 recent implementations
 - Memory leaks
 
 **4. Code Quality**

package/skills/debug/SKILL.md

@@ -71,3 +71,11 @@ When the bug is fixed, briefly report:
 - **Fix**: What was changed and why
 - **Test**: What test verifies the fix
 - **Prevention**: How to prevent similar bugs (if applicable)
+
+## Escalation
+
+If the 3-Strike Rule activates (3 fixes failed), suggest:
+> "This bug may need deeper investigation. Run `/hopla-rca` to produce a structured Root Cause Analysis document with evidence, proposed fix, and prevention steps."
+
+If the bug is fixed, suggest:
+> "Bug fixed. Run `/hopla-validate` to verify no regressions, then `/hopla-git-commit` to save the fix."

package/skills/execution-report/SKILL.md

@@ -101,7 +101,7 @@ New gotchas, patterns, or conventions learned during this implementation that sh
 
 - **Pattern/Gotcha:** [description]
 - **Where it applies:** [what type of feature or context triggers this]
-- **Suggested documentation:** [which file should capture this: CLAUDE.md, `.agents/guides/review-checklist.md`, or a new guide]
+- **Ready-to-paste CLAUDE.md entry:** [Write the EXACT text that should be added to the project's CLAUDE.md to prevent this gotcha in future features. Format it as a bullet point under the appropriate section. If it belongs in a guide instead, write the exact text for the guide. Do not write vague suggestions like "document this" — write the actual content so the system reviewer can apply it directly.]
 
 If nothing new was discovered, write "No new patterns discovered."
 

package/skills/git/commit.md

@@ -20,7 +20,10 @@ git log --oneline -5
 - 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`)
+- Resolve branch context using `flow-detection.md` (same directory):
+  - Confirm the current branch is NOT a base branch (`main`/`master`/`develop`/`dev`) — if it is, warn the user before committing
+  - Confirm the branch prefix matches `feature/`, `fix/`, `hotfix/`, or `release/` — otherwise ask the user
+  - Detect whether you are inside a worktree (via `git rev-parse --git-dir` vs `--git-common-dir`) and report the location to the user for context
 
 ## Step 3: Stage Files
 
@@ -42,7 +45,18 @@ Present the proposed commit message to the user **before executing**:
 
 Wait for explicit approval before running `git commit`.
 
-## Step 5: Execute Commit
+## Step 5: Version Bump (if configured)
+
+Before committing, check the project's `CLAUDE.md` for a `## Versioning` section. If it exists:
+
+1. Read the versioning configuration (command, trigger, files)
+2. Check if the **trigger condition** matches (e.g., specific branches, always, etc.)
+3. If it matches, run the version bump command
+4. Stage the version files alongside the other changes
+
+If no `## Versioning` section exists in the project's `CLAUDE.md`, skip this step entirely.
+
+## Step 6: Execute Commit
 
 Once approved, create the commit:
 
@@ -50,10 +64,13 @@ Once approved, create the commit:
 git commit -m "<type>(<scope>): <description>"
 ```
 
-## Step 6: Push Reminder
+## Step 7: 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.
+
+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/skills/git/flow-detection.md

@@ -0,0 +1,68 @@
+# Git Flow Detection — Shared Reference
+
+> Shared by the `git` skill (`commit.md`, `pr.md`), the `worktree` skill, and the `execute` command. Keep the logic here and reference it from callers — do not duplicate.
+
+## Step 1: Detect the branching model
+
+```bash
+git branch -r
+```
+
+Resolve `$DEFAULT_BASE`:
+
+- `origin/develop` exists → **Git Flow**, `$DEFAULT_BASE = develop`
+- Else `origin/dev` exists → **Git Flow**, `$DEFAULT_BASE = dev`
+- Else only `origin/main` / `origin/master` → **GitHub Flow**, `$DEFAULT_BASE = main` (or `master`)
+
+## Step 2: Map branch prefix → base branch
+
+| Branch prefix | Base (Git Flow) | Base (GitHub Flow) |
+|---|---|---|
+| `feature/*` | `$DEFAULT_BASE` | `main` |
+| `fix/*` | `$DEFAULT_BASE` | `main` |
+| `hotfix/*` | `main` | `main` |
+| `release/*` | `main` | N/A — ask the user |
+
+**Edge cases:**
+
+- Branch does not match a known prefix → ask the user which base to use
+- Current branch is `main`/`master`/`develop`/`dev` → stop and warn; commits and PRs must come from a feature/fix/hotfix/release branch
+- `hotfix/*` on a Git Flow project but base resolved to `develop` → **refuse** and correct to `main`
+
+## Step 3: Detect worktree context
+
+```bash
+GIT_DIR=$(git rev-parse --git-dir)
+GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
+```
+
+- `GIT_DIR` ≠ `GIT_COMMON_DIR` → you are **inside a worktree**
+- Else you are in the **main repo**
+
+List all active worktrees when useful for the user:
+
+```bash
+git worktree list
+```
+
+The main repo path is:
+
+```bash
+MAIN_REPO=$(dirname "$(git rev-parse --git-common-dir)")
+```
+
+## Step 4: Verify the resolved base exists remotely
+
+```bash
+git show-ref --verify --quiet refs/remotes/origin/$BASE || echo "missing"
+```
+
+If missing, ask the user before proceeding.
+
+## Step 5: Standard warnings
+
+Emit these to the user when applicable:
+
+- On `main`/`develop`/`dev`: "You're on `$BRANCH` — this is a base branch. Commits and PRs should come from feature branches."
+- Unknown prefix: "Branch `$BRANCH` does not match `feature/`, `fix/`, `hotfix/`, or `release/`. Which base branch should it target?"
+- Hotfix from wrong base: "`hotfix/*` must branch from `main`, not `$DETECTED_BASE`. Refusing to proceed — recreate the branch from `main`."

package/skills/git/pr.md

@@ -21,21 +21,16 @@ Read the following if they exist:
 
 **If the user specified a base branch**, use it.
 
-**Otherwise, infer from Git Flow branch naming:**
+**Otherwise**, resolve it using `flow-detection.md` (same directory):
 
-| Current branch prefix | Base branch |
-|---|---|
-| `feature/*` | `develop` or `dev` |
-| `fix/*` | `develop` or `dev` |
-| `hotfix/*` | `main` |
-| `release/*` | `main` |
+1. Detect the branching model and `$DEFAULT_BASE` (Step 1 of flow-detection.md)
+2. Map the current branch prefix → base branch (Step 2 of flow-detection.md)
+3. Verify the resolved base exists remotely (Step 4 of flow-detection.md)
+4. Apply the standard warnings (Step 5 of flow-detection.md)
 
-To resolve `develop` vs `dev`: run `git branch -r` and look for `origin/develop` or `origin/dev`. Use whichever exists.
+**Always show the resolved base branch in Step 5** so the user can catch mistakes before the PR is created.
 
-**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.
+Also detect if you are inside a worktree (Step 3 of flow-detection.md) — this is needed for post-merge cleanup in Step 7.
 
 ## Step 3: Check Push Status
 
@@ -94,11 +89,44 @@ 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:
+After the user confirms the PR was approved and merged on GitHub, detect whether the branch lives in a worktree and run the appropriate cleanup.
+
+### Detect worktree
+
+Apply Step 3 of `flow-detection.md`:
+
+```bash
+GIT_DIR=$(git rev-parse --git-dir)
+GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
+MAIN_REPO=$(dirname "$GIT_COMMON_DIR")
+```
+
+If `GIT_DIR` ≠ `GIT_COMMON_DIR`, the branch is in a worktree — use **Path A**. Otherwise use **Path B**.
+
+### Path A — Cleanup from a worktree
+
+Capture the worktree path before moving out:
+
+```bash
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+cd "$MAIN_REPO"
+
+git checkout [base-branch]
+git pull origin [base-branch]
+
+git worktree remove "$WORKTREE_PATH"
+git branch -d [merged-branch]
+git push origin --delete [merged-branch] 2>/dev/null  # skip if GitHub already deleted it
+```
 
-### For all branch types:
+If `git worktree remove` fails because the tree has uncommitted work, stop and ask the user — do **not** pass `--force` without explicit confirmation.
+
+### Path B — Cleanup from the main repo
 
 ```bash
 git checkout [base-branch]
@@ -107,7 +135,9 @@ 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/*`:
+**Important:** When `dev` is merged to `main` via PR, do NOT pull `main` back into `dev` — `dev` already has all the commits. Only sync `main` → `dev` for hotfix/release branches (see below).
+
+### Additional steps for `hotfix/*` and `release/*`
 
 These branches were merged to `main` but `develop` also needs the changes:
 
@@ -127,4 +157,4 @@ 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.
+**Always confirm each destructive action** (branch deletion, worktree removal, tag creation) before executing.

package/skills/verify/SKILL.md

@@ -62,3 +62,13 @@ Reference `/hopla-validate` for project-specific validation commands.
 - **Applies to**: Any declaration of completion, whether mid-conversation or at end of task
 - **Does NOT apply to**: Intermediate progress updates ("I've finished editing file X, moving to file Y")
 - **Partial completion**: You may say "file X is updated" without full validation, but "the feature is complete" requires the full gate
+
+## Plan Execution Check
+
+When verifying completion of a plan execution (not just a standalone task):
+
+1. **Divergences documented?** — Ask: "Were there any tasks added, skipped, or changed from the original plan?" If yes, verify they are documented in the completion report.
+2. **Unplanned files?** — Run `git diff --name-only` and compare against the plan's task list. Flag any files changed that aren't in any task.
+3. **All acceptance criteria met?** — Read the plan's acceptance criteria and verify each one has fresh evidence.
+
+These checks prevent the common pattern where implementation is "done" but divergences are silently omitted from the report.