@hopla/claude-setup 1.12.1 → 1.14.1

package/commands/code-review-fix.md

@@ -58,4 +58,4 @@ Provide a summary of:
 ## Next Step
 
 After all fixes pass validation, suggest:
-> "All review issues fixed and validation passed. Run `/hopla-execution-report` to document the implementation, then `/hopla-git-commit` to commit."
+> "All review issues fixed and validation passed. Run the `execution-report` skill to document the implementation, then the `git` skill (say "commit") to commit."

package/commands/create-prd.md

@@ -222,4 +222,4 @@ Do not ask clarifying questions about changes — just apply them and confirm wh
 1. Rename `PRD.draft.md` → `PRD.md` (overwrite if it existed)
 2. Rename any `.draft` context documents to their final names
 3. Delete all `.draft` files
-4. Confirm: "✅ `PRD.md` saved. Run `/hopla-git-commit` to save it to the repository."
+4. Confirm: "✅ `PRD.md` saved. Run the `git` skill (say "commit") to save it to the repository."

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:
@@ -147,7 +166,7 @@ Run integration tests or manual verification as specified in the plan (e.g. `npm
 Verify the feature works end-to-end.
 
 ### 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).
+Run a code review on all changed files following the the `code-review` skill 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**.
 
@@ -201,7 +220,7 @@ Provide a summary of what was done:
 ## Step 7: Suggest Next Steps
 
 After the summary, suggest:
-1. Run `/hopla-code-review` for a standalone review of the changes (recommended — a fresh review catches issues the executing agent may have missed)
-2. If issues are found, run `/hopla-code-review-fix` to fix them
-3. Run `/hopla-execution-report` to document the implementation
-4. Run `/hopla-git-commit` to commit the changes
+1. Run the `code-review` skill for a standalone review of the changes (recommended — a fresh review catches issues the executing agent may have missed)
+2. If issues are found, run `/hopla:code-review-fix` to fix them
+3. Run the `execution-report` skill to document the implementation
+4. Run the `git` skill (say "commit") to commit the changes

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.
@@ -39,19 +45,19 @@ Three categories for every task:
 ## Your Available Commands
 
 ### For Planning & Product
-- `/hopla-create-prd` — Create a Product Requirements Document through guided conversation
-- `/hopla-plan-feature` — Create an implementation plan (AI researches, you approve)
-- `/hopla-review-plan` — Review a plan before execution
+- `/hopla:create-prd` — Create a Product Requirements Document through guided conversation
+- `/hopla:plan-feature` — Create an implementation plan (AI researches, you approve)
+- `/hopla:review-plan` — Review a plan before execution
 
 ### For Oversight
-- `/hopla-system-review` — Analyze how well the AI followed the plan
-- `/hopla-guide` — Show this guide again
+- `/hopla:system-review` — Analyze how well the AI followed the plan
+- `/hopla:guide` — Show this guide again
 
 ## Getting Started
 
-1. Start with `/hopla-create-prd` to define your project scope
-2. Use `/hopla-plan-feature "your feature idea"` to plan each feature
-3. Review the plan with `/hopla-review-plan`
+1. Start with `/hopla:create-prd` to define your project scope
+2. Use `/hopla:plan-feature "your feature idea"` to plan each feature
+3. Review the plan with `/hopla:review-plan`
 4. Hand off to a developer for execution, or ask the AI to execute
 
 ## Tips for Better Results

package/commands/guides/ai-optimized-codebase.md

@@ -1,7 +1,7 @@
 # AI-Optimized Codebase Guide
 
 ## When to Use This Guide
-Reference this guide when initializing a project with `/hopla-init-project` or when optimizing an existing codebase for better AI-assisted development.
+Reference this guide when initializing a project with `/hopla:init-project` or when optimizing an existing codebase for better AI-assisted development.
 
 ## Principles
 

package/commands/guides/mcp-integration.md

@@ -5,17 +5,17 @@ Reference this guide when planning features that involve external tools or servi
 
 ## MCP in the PIV Loop
 
-### During Planning (`/hopla-plan-feature`)
+### During Planning (`/hopla:plan-feature`)
 - Check what MCP servers are configured (listed in CLAUDE.md under "MCP Servers")
 - For each external integration point, specify which MCP tool to use
 - Example: "Step 3: Use Playwright MCP to verify the component renders correctly"
 
-### During Execution (`/hopla-execute`)
+### During Execution (`/hopla:execute`)
 - Before starting, verify MCP servers are available and responsive
 - When a task involves an MCP tool, use it explicitly (don't fall back to manual alternatives)
 - If an MCP server is unavailable, document it and skip that validation step
 
-### During Validation (`/hopla-validate`)
+### During Validation (`/hopla:validate`)
 - Use Playwright MCP for E2E browser validation if configured
 - Use database MCPs to verify data state after migrations
 - Document which validations were done via MCP vs. manual

package/commands/guides/remote-coding.md

@@ -50,9 +50,9 @@ jobs:
         run: |
           npx claude-code --print "
             Read issue #${{ github.event.issue.number }}.
-            /hopla-plan-feature based on the issue requirements.
-            /hopla-execute the plan.
-            /hopla-validate
+            /hopla:plan-feature based on the issue requirements.
+            /hopla:execute the plan.
+            /hopla:validate
             Create a PR with the results.
           "
 ```

package/commands/guides/review-checklist.md

@@ -1,6 +1,6 @@
 # Guide: Creating a Project-Specific Review Checklist
 
-Use this guide to create a `.agents/guides/review-checklist.md` file in your project with code review checks specific to your tech stack, domain, and known anti-patterns. The `/hopla-code-review` command loads this file automatically when it exists, applying your custom checks alongside the standard review categories.
+Use this guide to create a `.agents/guides/review-checklist.md` file in your project with code review checks specific to your tech stack, domain, and known anti-patterns. The the `code-review` skill command loads this file automatically when it exists, applying your custom checks alongside the standard review categories.
 
 ---
 
@@ -9,8 +9,8 @@ Use this guide to create a `.agents/guides/review-checklist.md` file in your pro
 Create a review checklist when:
 - The same bug pattern appears in **2+ code reviews** (e.g., stale closures in grid callbacks)
 - Your project uses a framework with non-obvious gotchas (AG Grid, Hono, Prisma, D3, etc.)
-- A `/hopla-system-review` flags a recurring issue that should be caught during code review
-- A `/hopla-execution-report` documents a new technical pattern in its "Technical Patterns Discovered" section
+- A `/hopla:system-review` flags a recurring issue that should be caught during code review
+- A the `execution-report` skill documents a new technical pattern in its "Technical Patterns Discovered" section
 
 ---
 
@@ -67,8 +67,8 @@ Patterns that have caused bugs in this project before:
 ## Maintenance
 
 Update this file when:
-- `/hopla-system-review` flags a recurring bug pattern (3+ occurrences across reviews)
-- `/hopla-execution-report` discovers a new technical pattern in "Technical Patterns Discovered"
+- `/hopla:system-review` flags a recurring bug pattern (3+ occurrences across reviews)
+- the `execution-report` skill discovers a new technical pattern in "Technical Patterns Discovered"
 - A code review finds a bug that should have been caught by a checklist item
 - A framework is upgraded and known gotchas change
 

package/commands/guides/scaling-beyond-engineering.md

@@ -10,21 +10,18 @@ According to Anthropic's 2026 Agentic Coding Trends Report:
 - The barrier between "people who code" and "people who don't" is becoming permeable
 - Domain experts implementing solutions directly removes bottlenecks
 
-## HOPLA's Planning Mode
+## HOPLA for Non-Technical Users
 
-HOPLA already supports non-technical users via `--planning` mode:
-- Restricted command set (planning and review only)
-- Limited git permissions (read-only)
-- Focus on product decisions, not implementation
+Non-technical users can adopt HOPLA today by installing the plugin and focusing on product-planning commands. The 4D Framework guide (`/hopla:guide`) walks them through Description → Discernment → Delegation → Diligence without requiring them to write or review code directly.
 
 ## Expanding the Model
 
 ### Phase 1: Product Planning (Current)
 Non-technical users can:
-- Create PRDs with `/hopla-create-prd`
-- Plan features with `/hopla-plan-feature`
-- Review plans with `/hopla-review-plan`
-- Guide workflow with `/hopla-guide` (4D Framework)
+- Create PRDs with `/hopla:create-prd`
+- Plan features with `/hopla:plan-feature`
+- Review plans with `/hopla:review-plan`
+- Guide workflow with `/hopla:guide` (4D Framework)
 
 ### Phase 2: Assisted Creation (Future)
 Non-technical users could:

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/   <- the `execution-report` skill saves here (commit — needed for cross-session learning)
+├── system-reviews/      <- /hopla:system-review saves here (commit — needed for feedback loop)
+└── code-reviews/        <- the `code-review` skill 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)
@@ -474,6 +476,6 @@ Once confirmed:
 1. Save `CLAUDE.md` to the project root
 2. Create `.agents/` directory structure
 3. Update `.gitignore`
-4. If no PRD exists yet, tell the user: "Project initialized. Run `/hopla-create-prd` next to define the product scope, or `/hopla-plan-feature` to start planning a feature."
-   If a PRD already exists, tell the user: "Project initialized. Run `/hopla-plan-feature` to start planning the first feature."
-5. Suggest running `/hopla-git-commit` to save everything
+4. If no PRD exists yet, tell the user: "Project initialized. Run `/hopla:create-prd` next to define the product scope, or `/hopla:plan-feature` to start planning a feature."
+   If a PRD already exists, tell the user: "Project initialized. Run `/hopla:plan-feature` to start planning the first feature."
+5. Suggest running the `git` skill (say "commit") to save everything

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
 
@@ -156,7 +170,7 @@ 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 2.5 — Code Review:** Run the `code-review` skill 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
@@ -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
 
@@ -244,4 +260,4 @@ Before saving the draft, review the plan against these criteria:
 
 **Finalize:**
 1. Rename `.agents/plans/[feature-name].draft.md` → `.agents/plans/[feature-name].md` (overwrite if it already exists)
-2. Confirm: "✅ Plan saved to `.agents/plans/[feature-name].md`. Run `/hopla-review-plan .agents/plans/[feature-name].md` to review it, then `/hopla-execute .agents/plans/[feature-name].md` to implement it."
+2. Confirm: "✅ Plan saved to `.agents/plans/[feature-name].md`. Run `/hopla:review-plan .agents/plans/[feature-name].md` to review it, then `/hopla:execute .agents/plans/[feature-name].md` to implement it."

package/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.
 
@@ -55,9 +60,9 @@ What needs to change to resolve this
 How to prevent similar issues in the future
 
 ## Next Steps
-- [ ] Implement fix (run `/hopla-execute` with a plan, or fix directly if simple)
+- [ ] Implement fix (run `/hopla:execute` with a plan, or fix directly if simple)
 - [ ] Add regression test
-- [ ] Validate with `/hopla-validate`
+- [ ] Validate with `/hopla:validate`
 ```
 
 ## Output

package/commands/review-plan.md

@@ -48,5 +48,5 @@ After the summary, ask (in the user's language):
 
 **Review loop:**
 - If the user has questions → answer them based on the plan content
-- If the user requests changes → note them and tell the user to ask Robert to update the plan, or apply minor clarifications directly if they are unambiguous
-- If the user approves → confirm: "✅ Plan approved. Run `/hopla-execute $1` to start."
+- If the user requests changes → note them and suggest re-running `/hopla:plan-feature` to update the plan, or apply minor clarifications directly if they are unambiguous
+- If the user approves → confirm: "✅ Plan approved. Run `/hopla:execute $1` to start."

package/commands/validate.md

@@ -66,10 +66,10 @@ If anything failed and could not be fixed, list the remaining issues and suggest
 
 ## After Validation Passes
 
-- Suggest running `/hopla-code-review` if not already done
+- Suggest running the `code-review` skill if not already done
 - Remind that completion claims must be backed by this fresh validation evidence (see hopla-verify skill)
 
 ## Next Step
 
 After validation passes, suggest:
-> "All validation levels passed. Consider running `/hopla-code-review` for a deeper analysis — code review catches bugs in 79% of implementations that pass automated validation (stale closures, missing input validation, route shadowing, unhandled promise rejections). Run `/hopla-code-review` to check, or `/hopla-git-commit` to commit directly."
+> "All validation levels passed. Consider running the `code-review` skill for a deeper analysis — code review catches bugs in 79% of implementations that pass automated validation (stale closures, missing input validation, route shadowing, unhandled promise rejections). Run the `code-review` skill to check, or the `git` skill (say "commit") to commit directly."

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/env-protect.js

@@ -1,19 +1,50 @@
 #!/usr/bin/env node
-// PreToolUse hook: blocks reads/greps targeting .env files
+// PreToolUse hook: blocks reads/greps/Bash commands that expose .env secrets.
+// Hooks.json matcher must include Bash so Bash calls reach this script.
+
+function isEnvPath(p) {
+    if (typeof p !== "string" || !p) return false;
+    // Matches: .env, ./.env, path/.env, .env.local, .env.production, path/.env.X
+    return /(^|\/)\.env(\.\w+)?$/.test(p);
+}
+
+function commandReadsEnv(cmd) {
+    if (typeof cmd !== "string" || !cmd) return false;
+    // Split on shell word separators so we inspect each argument/path token
+    const tokens = cmd.split(/[\s<>|&;"'`()]+/);
+    return tokens.some(isEnvPath);
+}
 
 async function main() {
     const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
+    for await (const chunk of process.stdin) chunks.push(chunk);
+
+    let toolCall;
+    try {
+        toolCall = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+        // Malformed input — fail open so we never block legitimate tool use
+        process.exit(0);
     }
 
-    const toolCall = JSON.parse(Buffer.concat(chunks).toString());
-    const filePath = toolCall.tool_input?.file_path || toolCall.tool_input?.path || "";
+    const name = toolCall.tool_name || "";
+    const input = toolCall.tool_input || {};
+
+    // Read / Grep / Glob / Edit / Write — check file_path or path
+    const filePath = input.file_path || input.path || "";
+    if (isEnvPath(filePath)) {
+        process.stderr.write(
+            `Access denied: reading or editing .env files is blocked to prevent accidental secret exposure. ` +
+            `If you need env var names, check the README or ask the user.\n`
+        );
+        process.exit(2);
+    }
 
-    if (filePath.includes(".env")) {
+    // Bash — inspect the command string for tokens that read an .env file
+    if (name === "Bash" && commandReadsEnv(input.command)) {
         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`
+            `Access denied: this Bash command reads a .env file, which is blocked to prevent secret exposure. ` +
+            `If you need env var names, ask the user.\n`
         );
         process.exit(2);
     }

package/hooks/hooks.json

@@ -14,7 +14,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Read|Grep",
+        "matcher": "Read|Grep|Glob|Edit|Write|Bash",
         "hooks": [
           {
             "type": "command",

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"));