@hopla/claude-setup 1.5.0 → 1.7.0

package/README.md

@@ -163,20 +163,20 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 
 ### Feature development (PIV loop)
 ```
-/hopla-prime          → load context at session start
-/hopla-plan-feature   → research codebase and create plan
-/hopla-review-plan    → review plan summary and approve
-/hopla-execute        → implement the plan with validation
-/hopla-code-review    → technical review of changes
-/hopla-code-review-fix → fix issues found
-/hopla-git-commit     → save to git
-/hopla-git-pr         → open pull request on GitHub
+/hopla-prime            → load context at session start
+/hopla-plan-feature     → research codebase and create plan
+/hopla-review-plan      → review plan summary and approve
+/hopla-execute          → implement the plan with validation
+/hopla-code-review      → standalone review of changes
+/hopla-code-review-fix  → fix issues found
+/hopla-execution-report → document what was built
+/hopla-git-commit       → save to git
+/hopla-git-pr           → open pull request on GitHub
 ```
 
 ### After implementation
 ```
-/hopla-execution-report  → document what was built
-/hopla-system-review     → analyze plan vs. actual for process improvements
+/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.
@@ -202,25 +202,31 @@ Commands are modular — the output of one becomes the input of the next. Some c
 /hopla-plan-feature add user authentication
 → saves: .agents/plans/add-user-authentication.md
 
-# 2. Execute
+# 2. Review plan
+/hopla-review-plan .agents/plans/add-user-authentication.md
+
+# 3. Execute
 /hopla-execute .agents/plans/add-user-authentication.md
 → implements the plan, runs validation
 
-# 3. Review
+# 4. Code review
 /hopla-code-review
 → saves: .agents/code-reviews/add-user-authentication.md
 
-# 4. Fix issues
+# 5. Fix issues
 /hopla-code-review-fix .agents/code-reviews/add-user-authentication.md
 
-# 5. Commit
-/hopla-git-commit
-
 # 6. Document
 /hopla-execution-report
 → saves: .agents/execution-reports/add-user-authentication.md
 
-# 7. Improve process
+# 7. Commit
+/hopla-git-commit
+
+# 8. Pull request
+/hopla-git-pr
+
+# 9. Process improvement (after PR merge)
 /hopla-system-review .agents/plans/add-user-authentication.md .agents/execution-reports/add-user-authentication.md
 ```
 

package/files/commands/hopla-code-review-fix.md

@@ -46,3 +46,8 @@ Provide a summary of:
 - Issues skipped and why (if $2 scope was used)
 - Validation result ✅/❌
 - Any issues that could not be fixed automatically and require human review
+
+## 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."

package/files/commands/hopla-code-review.md

@@ -79,3 +79,8 @@ If no issues found: "Code review passed. No technical issues detected."
 - Focus on real bugs, not style preferences (linting handles that)
 - Flag security issues as `critical`
 - Suggest fixes, don't just identify problems
+
+## Next Step
+
+After the review, suggest:
+> "Code review saved to `.agents/code-reviews/[name].md`. If issues were found, run `/hopla-code-review-fix .agents/code-reviews/[name].md` to fix them. If the review passed clean, proceed to `/hopla-execution-report`."

package/files/commands/hopla-execute.md

@@ -62,6 +62,8 @@ 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]`)"
 - **If on a `feature/`, `fix/`, or `hotfix/` branch** — proceed
+- **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?"
 
 If a new branch is needed, propose the name and wait for confirmation before creating it:
 ```bash
@@ -99,6 +101,19 @@ Work through each task in the plan sequentially. For each task:
 
 Do not improvise silently. When in doubt, stop and ask.
 
+### Scope Guard
+
+If the user requests changes that are NOT in the plan during execution:
+
+1. **Acknowledge** the request
+2. **Assess** whether it's a small adjustment (< 5 minutes, same files) or a new feature
+3. **If small adjustment:** implement it and flag it as a deviation in the completion report
+4. **If new feature or significant addition:**
+   - Suggest committing the current planned work first
+   - Then create a new branch or add it to the backlog
+   - Say: "This looks like a separate feature. I recommend we commit the current work first, then handle this in a new branch. Should I add it to `.agents/plans/backlog/` instead?"
+5. **Never** silently add significant unplanned work — scope creep caused the lowest alignment score (6/10) in past implementations
+
 ## Step 5: Run Full Validation Pyramid
 
 After all tasks are complete, run the full validation sequence in order.
@@ -180,5 +195,7 @@ Provide a summary of what was done:
 ## Step 7: Suggest Next Steps
 
 After the summary, suggest:
-1. Run `/hopla-execution-report` to document this implementation for system review
-2. Run `/hopla-git-commit` once everything is approved
+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

package/files/commands/hopla-execution-report.md

@@ -67,3 +67,8 @@ Based on this implementation, what should change for next time?
 - Plan command improvements: [suggestions]
 - Execute command improvements: [suggestions]
 - CLAUDE.md additions: [suggestions]
+
+## Next Step
+
+After the report is saved, suggest:
+> "Execution report saved to `.agents/execution-reports/[name].md`. Run `/hopla-git-commit` to commit your changes."

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

@@ -45,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:
 
@@ -53,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/files/commands/hopla-git-pr.md

@@ -97,6 +97,9 @@ 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:

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

@@ -64,6 +64,9 @@ Based on research, define:
 - Any risks, edge cases, or gotchas to flag
 - What tests are needed
 - **Derived/computed values:** If any value is calculated from other fields, specify the exact formula including how stored values are interpreted (sign, units, semantics), AND how derived values propagate when inputs change (event system, reactivity, polling, etc.)
+- **Interaction states & edge cases:** For features involving interactive UI (forms, grids, keyboard navigation, wizards, CLI interactions), define a matrix of user interactions and their expected behavior. Cover: all keyboard shortcuts (both directions — e.g., Tab AND Shift+Tab), state transitions (empty → editing → saved → error), and boundary conditions (first item, last item, empty list, maximum items). This prevents iterative fix rounds that consumed up to 40% of session time in past implementations.
+- **API input validation:** For every API endpoint being created or modified, specify: required fields, field format constraints (e.g., "IMEI must be exactly 15 digits"), payload size limits, and what the user sees on validation failure. This was the #2 most common gap in past plans — validation was only added after code review in 4 of 7 implementations.
+- **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.
 
 ## Phase 5: Generate the Plan
 
@@ -85,6 +88,10 @@ Use this structure:
 ## Out of Scope
 - [Anything explicitly excluded]
 
+## Git Strategy
+- **Base branch:** `[develop | dev | main — specify which branch to create the feature branch from]`
+- **Feature branch:** `feature/[kebab-case-name]`
+
 ## Context References
 Key files the executing agent must read before starting:
 - `[path/to/file]` — [why it's relevant]
@@ -101,20 +108,34 @@ Key files the executing agent must read before starting:
 - **Details:** [Step-by-step description of what to implement]
 - **Gotcha:** [Known pitfall or constraint] — or `N/A`
 - **Validate:** [Exact command or check to confirm this task is done correctly]
+- **Time-box:** [Optional — for tasks with known technical risk, specify a maximum time and fallback. E.g., "30 min max. If auto-sizing doesn't work, fall back to fixed widths." Omit for straightforward tasks.]
 
 #### For tasks that create or modify API endpoints, also include:
 - **Validation:** [Required fields, input limits, format constraints (e.g. "IMEI must be exactly 15 digits")]
 - **Error UX:** [What the user sees when this operation fails (e.g. "toast.error with message", "inline error under field")]
 
 ### Task 2: [Action verb + what]
-[Same structure — all 6 fields required]
+[Same structure — all 6 required fields, plus optional Time-box]
 
 [Continue for all tasks...]
 
+## Interaction Matrix (if applicable)
+
+> Include this section when the feature involves interactive UI (grids, forms, keyboard navigation, drag-and-drop, wizards). Skip for pure backend/API features.
+
+| Action | Context | Expected Behavior |
+|--------|---------|-------------------|
+| [e.g., Tab] | [e.g., Last editable cell in row] | [e.g., Move to first cell of next row] |
+| [e.g., Escape] | [e.g., While editing a cell] | [e.g., Cancel edit, restore previous value] |
+
+Include: keyboard shortcuts (forward AND reverse), mouse interactions, state transitions, boundary conditions (first/last item, empty state, maximum items).
+
 ## Test Tasks
 
 > Every plan must include at least one task that creates or updates tests. If the feature is purely UI with no testable logic, specify which interactions to verify manually and why automated tests are not applicable.
 
+> **Regression check:** If this feature modifies existing interactive functionality (editing flows, keyboard navigation, API endpoints with existing consumers), include a task to smoke-test the existing behavior AFTER implementation. In past implementations, changes to shared utilities broke existing interactions that weren't covered by the plan's task list.
+
 ## Validation Checklist
 
 Run in this order — do not proceed if a level fails:
@@ -164,6 +185,9 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **Test coverage:** At least one task creates or updates tests — or a justification is provided for why tests are not applicable
 - [ ] **User preferences checked:** MEMORY.md was consulted for UI preferences (modal vs inline, keyboard shortcuts, component conventions) that affect the plan
 - [ ] **Confidence score justified:** Score is provided with specific strengths, uncertainties, and mitigations
+- [ ] **Git strategy specified:** Base branch and feature branch are defined in `## Git Strategy`
+- [ ] **Interaction matrix included:** If the feature involves interactive UI, the `## Interaction Matrix` section is filled out — or explicitly marked as N/A with justification
+- [ ] **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
 
 ## Phase 7: Save Draft and Enter Review Loop
 
@@ -192,4 +216,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-git-commit` to commit it, then share with the team to execute with `/hopla-execute .agents/plans/[feature-name].md`."
+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/package.json

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