@hopla/claude-setup 1.12.1 → 1.14.0

package/skills/worktree/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: worktree
-description: "Git worktree management for isolated feature development. Use when starting a new feature that benefits from isolation, when the user says 'worktree', 'isolated branch', 'parallel development', or when implementing multiple features simultaneously. Do NOT use for quick fixes or single-file changes."
+description: "Git worktree management for isolated feature development with Git Flow awareness. Use when starting a new feature that benefits from isolation, when the user says 'worktree', 'isolated branch', 'parallel development', or when implementing multiple features simultaneously. Do NOT use for quick fixes or single-file changes."
 ---
 
-# Git Worktrees for Isolated Development
+# Git Worktrees — Isolated Development with Git Flow
 
-## What Are Worktrees?
-Git worktrees create separate working directories for different branches, sharing the same git history. Each worktree is an independent workspace.
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+## What are worktrees?
+
+Git worktrees create separate working directories for different branches while sharing the same git history. Each worktree is an independent workspace.
+
+## When to use
 
-## When to Use
 - Starting a feature that should be isolated from other work
 - Developing multiple features in parallel
 - Needing a clean baseline to test against
@@ -16,58 +20,99 @@ Git worktrees create separate working directories for different branches, sharin
 
 ## Setup Process
 
-### Step 1: Choose Worktree Directory
+### Step 1: Identify branch type and resolve base branch
+
+Ask the user (or infer from context) which type of branch to create:
+
+| Prefix | Purpose | Base (Git Flow) | Base (GitHub Flow) |
+|---|---|---|---|
+| `feature/*` | New functionality | `develop` / `dev` | `main` |
+| `fix/*` | Non-urgent bug fix | `develop` / `dev` | `main` |
+| `hotfix/*` | Urgent production fix | `main` | `main` |
+| `release/*` | Release candidate | `main` | N/A — ask user |
+
+Use `../git/flow-detection.md` (Steps 1–2) to resolve the base branch from the prefix. Confirm it exists remotely (Step 4).
+
+**Guard rails:**
+
+- **Refuse** to create a `hotfix/*` worktree from `develop`/`dev`. Hotfixes must come from `main` — correct the base before proceeding.
+- If the prefix is unknown, ask the user which base to use.
+- Always show the resolved base to the user before executing `git worktree add`.
+
+### Step 2: Choose worktree directory
+
 Check in order:
+
 1. Existing `.worktrees/` or `worktrees/` directory
-2. CLAUDE.md preference (if configured)
-3. Ask the user
+2. `CLAUDE.md` preference (if configured)
+3. Ask the user (default: `worktrees/<kebab-name>`)
+
+### Step 3: Ensure the worktree directory is gitignored
 
-### Step 2: Ensure Directory is Gitignored
 ```bash
-# Verify the worktree directory is in .gitignore
-grep -q "worktrees" .gitignore || echo "worktrees/" >> .gitignore
+grep -q "^worktrees/" .gitignore 2>/dev/null || echo "worktrees/" >> .gitignore
 ```
 
-### Step 3: Create Worktree
+### Step 4: Create the worktree from the correct base
+
+Fetch first so the local base tracks the remote:
+
 ```bash
-# Create worktree with a new feature branch
-git worktree add worktrees/feature-name -b feature/feature-name
+git fetch origin <base-branch>
+git worktree add worktrees/<name> -b <prefix>/<name> origin/<base-branch>
 ```
 
-### Step 4: Setup Project in Worktree
-Auto-detect and run setup:
-- **Node.js**: `npm install` or `yarn install`
-- **Python**: `pip install -r requirements.txt` or `poetry install`
-- **Rust**: `cargo build`
-- **Go**: `go mod download`
+Examples:
 
-### Step 5: Verify Clean Baseline
 ```bash
-cd worktrees/feature-name
-# Run tests to ensure baseline is green
-npm test  # or equivalent
+# Feature off develop
+git worktree add worktrees/auth -b feature/auth origin/develop
+
+# Hotfix off main
+git worktree add worktrees/crash-fix -b hotfix/crash-fix origin/main
+
+# Fix on GitHub Flow project
+git worktree add worktrees/typo -b fix/typo origin/main
 ```
 
-If tests fail before any changes, STOP and report — the baseline is broken.
+### Step 5: Install project dependencies (if applicable)
+
+Auto-detect from the project root — run only what matches:
+
+- `package-lock.json` → `npm install`
+- `yarn.lock` → `yarn install`
+- `pnpm-lock.yaml` → `pnpm install`
+- `requirements.txt` → `pip install -r requirements.txt`
+- `pyproject.toml` with `poetry.lock` → `poetry install`
+- `Cargo.toml` → `cargo build`
+- `go.mod` → `go mod download`
+
+If none match, skip.
+
+### Step 6: Verify clean baseline (optional)
+
+If `CLAUDE.md` or `package.json` defines a test command, run it once inside the worktree to confirm the baseline is green. If no test command is defined, skip.
 
-### Step 6: Work in the Worktree
-All work for this feature happens in `worktrees/feature-name/`.
+If tests fail **before any changes**, STOP and report — the baseline is broken.
+
+### Step 7: Work in the worktree
+
+All work for this branch happens in `worktrees/<name>/`. Use the `git` skill from inside the worktree directory for commits and PRs — it detects the worktree context automatically.
 
 ## Cleanup
 
-### After Merge
-```bash
-git worktree remove worktrees/feature-name
-git branch -d feature/feature-name
-```
+Post-merge cleanup is handled by the `git` skill — see `../git/pr.md` Step 7. It detects the worktree and runs `git worktree remove` automatically.
+
+If the branch is **abandoned** before merge, confirm with the user and then:
 
-### If Abandoned
 ```bash
-git worktree remove --force worktrees/feature-name
-git branch -D feature/feature-name
+cd "$(dirname "$(git rev-parse --git-common-dir)")"  # back to main repo
+git worktree remove --force worktrees/<name>
+git branch -D <prefix>/<name>
 ```
 
 ## Integration
-- Use with `/hopla-execute` for isolated feature implementation
-- Use with `/hopla-git-pr` for creating PRs from the worktree branch
-- Combine with parallel dispatch for multiple features simultaneously
+
+- Combine with `/hopla-execute` — run execution from inside the worktree
+- Combine with the `git` skill — commit and PR from inside the worktree; cleanup happens post-merge
+- Combine with parallel dispatch — multiple worktrees active simultaneously

package/commands/end-to-end.md

@@ -1,67 +0,0 @@
-# End-to-End Feature Implementation
-
-> Execute the complete PIV loop for a feature in one go: prime → brainstorm → plan → review → execute → validate → commit.
-
-> ⚠️ **Advanced**: Only use this command after you've proven each individual command works reliably. Build trust gradually.
-
-## Input
-- `$ARGUMENTS`: Feature description or requirement
-
-## Autonomy Levels
-
-This command represents **Level 3 autonomy**. Make sure you've mastered:
-- Level 1: Manual prompts (writing everything each time)
-- Level 2: Individual commands (/hopla-plan-feature, /hopla-execute, etc.)
-- Level 3: Command chaining (this command)
-
-## Process
-
-### Phase 1: Context Loading
-Load project context:
-- Read CLAUDE.md, README, package.json
-- Check git state (branch, status, pending plans)
-- Identify current development phase
-
-### Phase 2: Brainstorm (if needed)
-If the feature is non-trivial (estimated > 1 hour):
-- Explore 2-3 approaches with trade-offs
-- Get user approval on approach
-- Save design doc to `.agents/specs/`
-
-If trivial: skip to Phase 3.
-
-### Phase 3: Plan
-- Research codebase for related patterns
-- Generate structured implementation plan
-- Save to `.agents/plans/[feature-name].md`
-
-### 🔒 GATE: Plan Review
-**STOP and present the plan to the user.**
-- Show executive summary
-- Wait for explicit approval before proceeding
-- If changes requested: iterate on the plan
-
-### Phase 4: Execute
-- Create feature branch (`feature/[name]` from develop)
-- Execute all plan tasks sequentially
-- Validate after each phase boundary
-
-### Phase 5: Validate
-- Run full validation pyramid (lint → types → tests → integration)
-- Run code review
-- Fix any critical/important issues found
-
-### 🔒 GATE: Human Review
-**STOP and present results to the user.**
-- Show what was built, what was validated
-- Wait for approval before committing
-
-### Phase 6: Commit & PR
-- Create conventional commit(s)
-- Suggest creating a PR if on a feature branch
-
-## Rules
-- Never skip the human gates (plan review, final review)
-- If any phase fails, stop and report — don't push through
-- Each phase should feel like a natural conversation, not a script
-- Adapt: skip brainstorming for small features, skip PR for hotfixes

package/commands/git-commit.md

@@ -1,76 +0,0 @@
----
-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
-
-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: 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:
-
-```bash
-git commit -m "<type>(<scope>): <description>"
-```
-
-## 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/commands/git-pr.md

@@ -1,138 +0,0 @@
----
-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
-
-```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 `$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
-
-```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.
-
-After showing the PR URL, suggest:
-> "PR created. To complete the cycle, run `/hopla-execution-report` (if not done yet) and `/hopla-system-review` after the PR is merged."
-
-## Step 7: Post-Merge Cleanup
-
-After the user confirms the PR was approved and merged on GitHub, run the cleanup workflow based on the branch type:
-
-### For feature and fix branches (merged to `dev`/`develop`):
-
-```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
-```
-
-**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/*` ONLY:
-
-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.