@hopla/claude-setup 1.16.0 → 1.17.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "hopla",
       "description": "Agentic coding system: PIV loop, TDD, debugging, brainstorming, subagent execution, and team workflows",
-      "version": "1.16.0",
+      "version": "1.17.0",
       "source": "./",
       "author": {
         "name": "Hopla Tools",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hopla",
   "description": "Agentic coding system for Claude Code: PIV loop (Plan → Implement → Validate), TDD, debugging, brainstorming, subagent execution, and team workflows",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"

package/README.md

@@ -233,6 +233,9 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 | `brainstorm` | "let's brainstorm", "explore approaches" |
 | `debug` | "debug this", "find the bug", "why is this failing" |
 | `tdd` | "write tests first", "TDD", "red-green-refactor" |
+| `refactoring` | "refactor", "clean up", "simplify", "extract", "deduplicate" |
+| `performance` | "slow", "optimize", "bottleneck", "lento", "tarda mucho" |
+| `migration` | "migrate", "upgrade", "switch from X to Y", "major version bump" |
 | `subagent-execution` | "use subagents", plans with 5+ tasks |
 | `parallel-dispatch` | "run in parallel", "parallelize this", independent tasks |
 
@@ -441,6 +444,7 @@ project/
 │   ├── rca/                       ← Root cause analysis docs (commit)
 │   ├── execution-reports/         ← Post-implementation reports (commit)
 │   ├── system-reviews/            ← Process improvement reports (commit)
+│   ├── audits/                    ← Persistent audit reports (commit — opt-in)
 │   └── code-reviews/              ← Code review reports (don't commit — ephemeral)
 └── .claude/
     └── commands/                  ← Project-specific commands (optional)

package/commands/init-project.md

@@ -435,9 +435,15 @@ Create the following directories (with `.gitkeep` where needed):
 ├── 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)
+├── audits/              <- persistent audit reports worth preserving (commit — opt-in; copy a code review here when you want to keep it)
 └── code-reviews/        <- the `code-review` skill saves here (do NOT commit — ephemeral, consumed by code-review-fix)
 ```
 
+**Policy — `audits/` vs `code-reviews/`:**
+
+- `code-reviews/` is **ephemeral working state**. Every run overwrites/adds files; `code-review-fix` consumes them and they become stale fast. Never commit.
+- `audits/` is **persistent**. Move or copy a review here when it documents a finding the team should remember (security issue, architectural concern, post-mortem evidence). Commit.
+
 Add to `.gitignore` (create if it doesn't exist):
 ```
 .agents/code-reviews/

package/commands/plan-feature.md

@@ -27,8 +27,9 @@ Read the following to understand the project:
 2. `README.md` — project overview and setup
 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.
+5. `.agents/specs/` — if this directory exists, scan for design specs that match the feature name. These come from the `brainstorm` skill and already document the chosen approach, files affected, edge cases, and open questions. If a matching spec exists, it is the authoritative design — the plan turns that design into tasks. If no spec exists and the feature is non-trivial, suggest running the `brainstorm` skill first.
+6. `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)
+7. `.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:
 

package/package.json

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

package/skills/migration/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: migration
+description: "Phased migration workflow for upgrading dependencies, switching frameworks, or moving between systems. Use when the user says 'migrate', 'upgrade', 'switch from X to Y', 'move to', 'replace library', 'major version bump', 'deprecated', or when changing a framework/runtime/database version. Do NOT use for greenfield features or small refactors — use plan-feature or refactoring instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Migration: Move Systems Without Breaking Them
+
+## Iron Rule
+
+**Every migration needs a rollback plan before the first line changes.** If you cannot describe how to undo the migration in one sentence, you are not ready to start it.
+
+## Step 1: Classify the Migration
+
+Ask the user (one question at a time):
+
+- **Type**: dependency upgrade (major version), framework switch (e.g. Express → Hono), runtime switch (Node → Bun), data store (SQLite → Postgres), API version (v1 → v2)
+- **Scope**: one module, one service, or the whole codebase?
+- **Downtime tolerance**: blue/green, zero-downtime (dual-run), acceptable window?
+- **Deadline driver**: deprecation, security, performance, or opportunistic?
+
+This framing determines whether the work is a single PR or a multi-phase plan.
+
+## Step 2: Audit the Surface
+
+Map **everything** that will be affected:
+
+- Imports / usages of the old API (use `grep -r` or `rg` across the codebase)
+- Public contracts that depend on current behavior (downstream callers, API consumers)
+- Build / deploy steps tied to the current version
+- Test suites that assume old behavior
+- Documentation mentioning the old API
+
+Write the inventory to `.agents/specs/migration-<topic>.md` with counts — "47 import sites across 12 files". Numbers help you size the work honestly.
+
+## Step 3: Read the Upgrade Notes
+
+Before writing code, read the target's official migration guide / changelog end to end. Note:
+
+- **Breaking changes** (renamed APIs, removed APIs, default-behavior flips)
+- **Deprecations** (will break in N+2, not now)
+- **Required minimum versions** for peer dependencies
+- **Data-shape changes** that require a migration script
+
+If the target project has no migration guide, treat it as higher risk and budget more time for exploration.
+
+## Step 4: Choose a Strategy
+
+| Strategy | When to use |
+|---|---|
+| **Big bang** | Small codebase, low downstream coupling, clean cut possible |
+| **Incremental with adapter** | Many call sites — introduce a thin wrapper that presents the old API on top of the new, migrate call sites one by one |
+| **Dual-run (strangler fig)** | High-risk or zero-downtime — run both old and new side by side, shift traffic gradually |
+| **Branch by abstraction** | Internal refactor + external API stays stable — hide the switch behind an interface |
+
+Pick one and document the trade-off in the spec file.
+
+## Step 5: Plan the Phases
+
+For anything non-trivial, run `/hopla:plan-feature` with `migration-<topic>` as the feature name. The plan should specify:
+
+- **Phase boundaries** (compatibility shim in, call sites migrated, shim removed)
+- **Rollback plan per phase** (revert commit? feature flag? dual-write?)
+- **Validation at each phase** (test suite green, feature flags covered, canary metrics)
+- **Data migration script** (if the storage layer changes) — idempotent, resumable
+
+Each phase should land as its own PR.
+
+## Step 6: Migrate With Guardrails
+
+Execute phase by phase. After every phase:
+
+- Run the full validation pyramid (`commands/guides/validation-pyramid.md`)
+- Check for mixed-version pitfalls — modules importing both the old and new API in the same request
+- Confirm the rollback path still works (git revert + redeploy, or feature flag off)
+
+Never advance to the next phase if validation failed on the previous one.
+
+## Step 7: Remove the Old Path
+
+Once every call site is migrated and observed green in production (where applicable):
+
+- Delete the compatibility shim
+- Remove the old dependency (`npm uninstall`, etc.)
+- Remove the feature flag
+- Update documentation to reference only the new path
+
+This "cleanup" step is part of the migration. A migration left half-done with a permanent shim is worse than no migration.
+
+## Rules
+
+- Never migrate on a Friday or before a public release
+- Keep the rollback plan alive at every phase — if it stops working, pause
+- Track breaking changes from the target's changelog in the spec, not in memory
+- Data migrations must be idempotent and resumable — migrations fail mid-run
+- If the migration drags past its original estimate by 2x, stop and reassess scope
+
+## Integration
+
+- Use `/hopla:plan-feature` to generate the phased plan from the Step 2 inventory
+- Use the `worktree` skill to keep the migration isolated from other work
+- The `code-review` skill (checklist sections 2 and 5) catches dual-import patterns and pattern drift
+- The `performance` skill verifies the migration did not regress hot paths
+
+## Next Step
+
+Once the migration is planned:
+
+> "Migration classified and inventoried. Saved spec to `.agents/specs/migration-<topic>.md`. Run `/hopla:plan-feature` to generate the phased implementation plan."

package/skills/performance/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: performance
+description: "Measured performance optimization workflow. Use when the user says 'slow', 'optimize', 'performance', 'bottleneck', 'too slow', 'high memory', 'high CPU', 'lento', 'tarda mucho', or when asking to make something faster. Do NOT use for correctness bugs or new features — use the debug or plan-feature skills instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Performance: Measure Before You Change
+
+## Iron Rule
+
+**No optimization without a measurement.** Every performance change must start with a number (latency, memory, query count) and end with a comparison. Guessing at hot paths wastes time and often makes things slower.
+
+## Step 1: Clarify the Symptom
+
+Ask the user (one question at a time):
+
+- What operation feels slow? (page load, API request, build, test run, specific query)
+- How slow is it? (exact number if possible — "3 seconds", "30 MB", "10s with 100 items")
+- What is "fast enough"? (target: < 500 ms p95, < 100 MB, etc.)
+- Is it reproducible, or only under load?
+
+Without a concrete target, you cannot declare the optimization done.
+
+## Step 2: Measure the Baseline
+
+Pick the right tool for the symptom:
+
+| Symptom | Measurement |
+|---|---|
+| Slow endpoint | `curl -w "%{time_total}"` or APM dashboard (see `guides/mcp-integration.md` for MCP options) |
+| Slow DB query | `EXPLAIN ANALYZE` (Postgres), `EXPLAIN` (SQLite/MySQL) |
+| Slow frontend render | Chrome DevTools Performance tab, React Profiler |
+| Memory growth | `process.memoryUsage()` snapshots, heap dumps |
+| Slow build/test | Time the command, compare against a clean cache |
+
+Record the baseline with units. "3.2 s to load /dashboard with 1000 items" — not "it feels slow".
+
+## Step 3: Identify the Hot Path
+
+Rank suspects by where the baseline measurement actually spends its time:
+
+- **N+1 queries** — are there loops calling the DB or an API?
+- **Missing indexes** — does `EXPLAIN ANALYZE` show a seq scan on a large table?
+- **Synchronous I/O** — is there a blocking call that could be awaited in parallel (`Promise.all`)?
+- **Rendering** — are components re-rendering with unchanged props? Are lists virtualized?
+- **Algorithm** — is there an O(n²) that could be O(n) with a map?
+- **Caching** — is the same computation repeated without memoization?
+
+Do **not** guess. Use the profiler output or query plan to pick one suspect.
+
+## Step 4: Apply One Change
+
+Change one thing. Not three.
+
+- Add the index
+- Replace the loop with `Promise.all`
+- Memoize the expensive selector
+- Batch the API calls
+- Virtualize the list
+
+Keep the diff minimal so you can attribute the delta to this change alone.
+
+## Step 5: Measure Again
+
+Re-run the exact same measurement from Step 2 under the same conditions. Report:
+
+- Baseline: X
+- After change: Y
+- Delta: (X − Y) / X × 100 %
+- Target: [target from Step 1]
+
+If you did not hit the target, go back to Step 3 and pick the next suspect. If you regressed, revert and rethink.
+
+## Step 6: Regression Guard
+
+Once the target is met, add a guard so future changes do not erode the win:
+
+- A test with a timeout assertion (e.g. `expect(duration).toBeLessThan(500)`)
+- A query count assertion (e.g. `expect(dbQueries).toHaveLength(1)`)
+- A bundle size budget, memory budget, or frame budget if applicable
+
+Without a guard, the win decays.
+
+## Rules
+
+- One suspect at a time — never stack optimizations before measuring
+- Keep the baseline in the commit message so the win is auditable
+- If the fix adds significant complexity for a small win (< 10 %), consider reverting
+- Do not optimize code that is not actually hot — premature optimization hurts readability
+
+## Integration
+
+- Use the `code-review` skill checklist section 3 (Performance Problems) for patterns to watch for
+- If the optimization requires architectural changes, stop and run `/hopla:plan-feature`
+- After the change lands, the `verify` skill will require the regression guard to run fresh
+
+## Next Step
+
+After the target is met and a regression guard is in place:
+
+> "Target hit: [baseline → result]. Regression guard added. Say 'commit' to trigger the `git` skill with a `perf:` conventional commit."

package/skills/refactoring/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: refactoring
+description: "Safe refactoring workflow with behavior preservation. Use when the user says 'refactor', 'clean up', 'simplify', 'extract', 'restructure', 'deduplicate', 'rename', or when asking to improve code structure without changing behavior. Do NOT use for bug fixes, new features, or performance work — use the debug, plan-feature, or performance skills instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Refactoring: Restructure Without Changing Behavior
+
+## Iron Rule
+
+**Behavior must be identical before and after.** If a refactor changes observable behavior — output, side effects, error shape, API surface — it is not a refactor. Stop and reclassify the work as a feature change or a bug fix.
+
+## Step 1: Confirm the Refactor Is Worth Doing
+
+Ask the user (one question at a time):
+
+- What is the current pain? (duplication, unclear naming, deep nesting, coupled modules)
+- What is the desired structure? (extract helper, collapse abstraction, rename, move, inline)
+- Is there a test suite, and does it cover the code being refactored?
+
+If the answers reveal a missing test covering the target, **write the test first** (pin current behavior), then refactor. Untested refactors are rewrites.
+
+## Step 2: Capture the Baseline
+
+Run the project's validation commands from `CLAUDE.md` (or use `/hopla:validate`). Record:
+
+- Lint / format — current state
+- Types — current state
+- Unit tests — pass/fail count
+- Relevant integration tests — pass/fail
+
+Every level must be green before starting. A refactor on top of red tests cannot prove it preserved behavior.
+
+## Step 3: Apply the Smallest Safe Change
+
+Pick one refactor at a time:
+
+- Extract function / module
+- Rename (symbol, file)
+- Inline (remove pointless indirection)
+- Move (relocate to a better home)
+- Deduplicate (merge two near-identical pieces)
+- Replace conditional with polymorphism / table lookup
+- Flatten / collapse nesting
+
+**Do not** mix refactors. If the change wants to become a redesign, stop and suggest `/hopla:plan-feature`.
+
+## Step 4: Re-run the Baseline
+
+After each refactor, re-run the same validation set from Step 2. Results must match exactly:
+
+- Same lint result (0 new warnings unless whitelisted)
+- Same type result
+- Same pass/fail count on tests
+- Same integration result
+
+If anything diverges, the refactor leaked behavior — revert or fix before continuing.
+
+## Step 5: Commit at a Clean Boundary
+
+When the baseline is restored and the refactor is coherent, suggest a commit via the `git` skill:
+
+> "Refactor complete — behavior preserved. Say 'commit' to save it with a `refactor:` conventional commit."
+
+## Rules
+
+- One refactor per commit — easier to review, easier to revert
+- Never combine refactor + feature in the same commit
+- Prefer many small refactors over one large one
+- If the test suite is missing, add tests FIRST, then refactor (two commits minimum)
+- Preserve public API unless the user explicitly approves a breaking change
+
+## Integration
+
+- Pair with the `tdd` skill when adding characterization tests before a refactor
+- Use the `code-review` skill after the refactor to confirm no pattern violations were introduced
+- If the refactor touches many files, consider the `worktree` skill for isolation
+
+## Next Step
+
+After the refactor passes validation:
+
+> "Refactor complete and validated. Say 'commit' to trigger the `git` skill with a `refactor:` conventional commit."